@merchi/sdk 1.40.2

package/src/pricing/estimate.ts

@@ -0,0 +1,310 @@
+import {
+  PricingRules, PricingField, PricingOption, Selections, FieldSelection,
+  QuoteResult, UnsupportedResult, DiscountGroup,
+} from './types.js';
+import { applyDiscount } from './discount.js';
+import { roundHalfEven } from './round.js';
+import { resolveVisibleFields } from './visibility.js';
+import { FieldType } from '../constants/field_types.js';
+
+/** Form inputs often supply quantities as strings. Coerce before any arithmetic
+ * so `reduce((a,b)=>a+b)` cannot concatenate ("100"+"1" → "01001" → 1001). */
+function toQuantity(value: unknown): number {
+  const n = Number(value);
+  return Number.isFinite(n) ? n : 0;
+}
+
+function parseAreaMm(
+  value: string | number | null | undefined
+): { heightMm: number; widthMm: number } | null {
+  if (value === undefined || value === null || value === '') return null;
+  const parts = String(value).split(',').map((p) => p.trim());
+  if (parts.length !== 2) return null;
+  const heightMm = Number(parts[0]);
+  const widthMm = Number(parts[1]);
+  if (!Number.isFinite(heightMm) || !Number.isFinite(widthMm)) return null;
+  if (heightMm <= 0 || widthMm <= 0) return null;
+  return { heightMm, widthMm };
+}
+
+function unitPriceAt(rules: PricingRules, qty: number): number {
+  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: { variationCost: number; variationCostDiscountGroup: DiscountGroup | null },
+  totalQty: number
+): number {
+  let cost = source.variationCost;
+  if (source.variationCostDiscountGroup) {
+    cost = applyDiscount(cost, totalQty, source.variationCostDiscountGroup);
+  }
+  return roundHalfEven(cost, 3);
+}
+
+function variationUnitCosts(
+  source: { variationUnitCost: number; variationUnitCostDiscountGroup: DiscountGroup | null },
+  groupQuantities: number[]
+): number[] {
+  const uc = source.variationUnitCost;
+  const group = source.variationUnitCostDiscountGroup;
+  let list: number[];
+  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: PricingField, sel: FieldSelection | undefined): boolean {
+  if (!sel) return true;
+  if (field.isSelectable) {
+    return !sel.selectedOptionIds || sel.selectedOptionIds.length === 0;
+  }
+  // Server `is_empty` non-selectable branch is `return not self.value`, so
+  // numeric 0 is empty (but string '0' stays non-empty, since `not '0'` is False).
+  return (
+    sel.value === undefined ||
+    sel.value === null ||
+    sel.value === '' ||
+    sel.value === 0
+  );
+}
+
+function areaCostFactor(
+  field: PricingField,
+  sel: FieldSelection | undefined,
+  groupQuantities: number[]
+): { setup: number; unitList: number[] } {
+  const n = groupQuantities.length;
+  const parsed = parseAreaMm(sel?.value ?? null);
+  if (!parsed) {
+    return { setup: 0, unitList: new Array(n).fill(0) };
+  }
+  const totalQty = groupQuantities.reduce((a, b) => a + b, 0);
+  const heightSetup = variationSetupCost(
+    {
+      variationCost: field.heightVariationCost || 0,
+      variationCostDiscountGroup: field.heightVariationCostDiscountGroup ?? null,
+    },
+    totalQty
+  );
+  const widthSetup = variationSetupCost(
+    {
+      variationCost: field.widthVariationCost || 0,
+      variationCostDiscountGroup: field.widthVariationCostDiscountGroup ?? null,
+    },
+    totalQty
+  );
+  const heightUcs = variationUnitCosts(
+    {
+      variationUnitCost: field.heightVariationUnitCost || 0,
+      variationUnitCostDiscountGroup:
+        field.heightVariationUnitCostDiscountGroup ?? null,
+    },
+    groupQuantities
+  );
+  const widthUcs = variationUnitCosts(
+    {
+      variationUnitCost: field.widthVariationUnitCost || 0,
+      variationUnitCostDiscountGroup:
+        field.widthVariationUnitCostDiscountGroup ?? null,
+    },
+    groupQuantities
+  );
+  const areaUnit = (field.areaUnit || 'mm').toLowerCase();
+  const mmPerUnit =
+    areaUnit === 'm' ? 1000
+    : areaUnit === 'cm' ? 10
+    : areaUnit === 'in' || areaUnit === 'inch' || areaUnit === 'inches' ? 25.4
+    : areaUnit === 'ft' || areaUnit === 'foot' || areaUnit === 'feet' ? 304.8
+    : 1;
+  const heightU = parsed.heightMm / mmPerUnit;
+  const widthU = parsed.widthMm / mmPerUnit;
+  const area = heightU * widthU;
+  // onceOff/unit = rateH × rateW × height_u × width_u (in field areaUnit)
+  const setup = roundHalfEven(heightSetup * widthSetup * area, 3);
+  const unitList = heightUcs.map((hu, i) =>
+    roundHalfEven(hu * widthUcs[i] * area, 3)
+  );
+  return { setup, unitList };
+}
+
+function costFactor(
+  field: PricingField,
+  sel: FieldSelection | undefined,
+  groupQuantities: number[]
+): { setup: number; unitList: number[] } {
+  const n = groupQuantities.length;
+  // Coerce: JSON/APIs occasionally deliver fieldType as a string.
+  if (Number(field.fieldType) === FieldType.AREA) {
+    return areaCostFactor(field, sel, groupQuantities);
+  }
+  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<number, PricingOption>();
+    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: PricingRules,
+  selections: Selections
+): QuoteResult | UnsupportedResult {
+  if (rules.unsupported) {
+    return { unsupported: rules.unsupported };
+  }
+
+  const groupCosts: number[] = [];
+  let cost = 0;
+  let costPerUnit: number;
+  let groupQuantities: number[];
+
+  // Mirror the server's `update_group_variations_cost_and_job_cost`
+  // (jobs.py ~3321): the group-vs-single branch keys off whether the *job*
+  // actually has variation groups (`if self.variations_groups:`), NOT the
+  // product's `hasGroups` capability. A group-capable product with no groups
+  // submitted is priced as a single non-group job (the server's `else` branch
+  // sets `group_quantities = [self.quantity or 0]`).
+  const groups = selections.groups || [];
+  if (groups.length > 0) {
+    groupQuantities = groups.map((g) => toQuantity(g.quantity));
+    const totalQty = groupQuantities.reduce((a, b) => a + b, 0);
+    const restricted = Boolean(rules.product.discountGroup?.groupRestricted);
+    const baseUnitPrice = unitPriceAt(rules, totalQty);
+    const perGroupCpu: number[] = [];
+
+    for (let gi = 0; gi < groups.length; gi++) {
+      const group = groups[gi];
+      const gQty = groupQuantities[gi];
+      const cpu = restricted ? unitPriceAt(rules, gQty) : baseUnitPrice;
+      perGroupCpu.push(cpu);
+      // Server `VariationsGroups.update_cost` (variations_groups.py ~238):
+      // `if not self.quantity: self.group_cost = 0; return` — a zero-qty group
+      // contributes exactly 0 and adds NO field/variation costs.
+      if (!gQty) {
+        groupCosts.push(0);
+        continue;
+      }
+      // A group's field visibility is scoped to that group's own selections
+      // plus the job-level (independent) selections — NOT other groups'
+      // (server `VariationsGroups.selected_options` = group.variations +
+      // job.variations, variations_groups.py ~252).
+      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 (job-level) field visibility is scoped to independent
+    // selections only (server `Jobs.selected_options` = job.variations,
+    // jobs.py ~1392), so other groups' selections never reveal them.
+    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 = toQuantity(selections.quantity);
+    groupQuantities = [qty];
+    costPerUnit = unitPriceAt(rules, qty);
+    cost = costPerUnit * qty;
+    // No groups: single-job scope (resolveVisibleFields with no groups uses
+    // only the top-level selections and considers only independent fields).
+    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;
+    }
+  }
+
+  // Server `Jobs.apply_product_setup_price`: product setup fee once per job,
+  // or once per non-empty group when setupPerGroup is true. With no groups the
+  // job is a single group, so setup is charged once either way.
+  const setupPrice = rules.product.setupPrice || 0;
+  if (setupPrice) {
+    if (groups.length > 0 && rules.product.setupPerGroup) {
+      for (let gi = 0; gi < groups.length; gi++) {
+        if (!groupQuantities[gi]) continue;
+        groupCosts[gi] += setupPrice;
+        cost += setupPrice;
+      }
+    } else {
+      cost += setupPrice;
+    }
+  }
+
+  // Server `Jobs.update_cost` (jobs.py ~3452-3454) accumulates `self.cost` at
+  // full precision and computes `self.tax_amount = tax(self.cost, ...)` on the
+  // UNROUNDED cost (money_protocol.py `tax` does NOT round). `cost` and
+  // `taxAmount` are then rounded INDEPENDENTLY at serialization to 2dp
+  // (jobs.py ~2169-2171). So tax must be derived from the unrounded cost.
+  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` mirrors `Jobs.all_total_cost` = `self.cost + self.tax_amount`
+    // (jobs.py ~1724), serialized UNROUNDED at jobs.py ~1899. We round to 3dp to
+    // strip float noise while matching the server's effective Numeric scale.
+    totalCost: roundHalfEven(unroundedCost + unroundedTax, 3),
+    // `result["groupCost"] = self.group_cost` is serialized UNROUNDED
+    // (variations_groups.py ~154); round to 3dp to match the Numeric scale.
+    groupCosts: groupCosts.map((c) => roundHalfEven(c, 3)),
+    currency: rules.currency,
+  };
+}

package/src/pricing/golden.test.ts

@@ -0,0 +1,51 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { estimateQuote } from './estimate.js';
+import { resolveVisibleFields } from './visibility.js';
+import { PricingRules, Selections, QuoteResult } from './types.js';
+
+// Fixtures are vendored into the SDK so the golden parity test is
+// self-contained in CI. They are generated by the merchi_api fixture
+// generator (tests/tests/pricing_fixtures.py) from the real server estimate.
+const FIXTURES_DIR = path.resolve(__dirname, '__fixtures__');
+
+interface Fixture {
+  name: string;
+  bundle: PricingRules;
+  selections: Selections;
+  expected: {
+    cost: number; costPerUnit: number; taxAmount: number; totalCost: number;
+    groupCosts: number[]; visibleFieldIds: number[];
+  };
+}
+
+function loadFixtures(): Fixture[] {
+  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')));
+}
+
+const fixtures = loadFixtures();
+
+test('pricing fixtures exist', () => {
+  expect(fixtures.length).toBeGreaterThan(0);
+});
+
+describe.each(fixtures)('golden parity: $name', (fixture: Fixture) => {
+  test('estimateQuote matches server', () => {
+    const result = estimateQuote(fixture.bundle, fixture.selections) as QuoteResult;
+    expect(result.cost).toBeCloseTo(fixture.expected.cost, 2);
+    expect(result.costPerUnit).toBeCloseTo(fixture.expected.costPerUnit, 3);
+    expect(result.taxAmount).toBeCloseTo(fixture.expected.taxAmount, 2);
+    expect(result.totalCost).toBeCloseTo(fixture.expected.totalCost, 2);
+    expect(result.groupCosts.length).toBe(fixture.expected.groupCosts.length);
+    result.groupCosts.forEach((c, i) =>
+      expect(c).toBeCloseTo(fixture.expected.groupCosts[i], 2));
+  });
+
+  test('resolveVisibleFields matches server', () => {
+    const visible = [...resolveVisibleFields(fixture.bundle, fixture.selections)].sort((a, b) => a - b);
+    expect(visible).toEqual(fixture.expected.visibleFieldIds);
+  });
+});

package/src/pricing/index.test.ts

@@ -0,0 +1,9 @@
+import { pricing } from '../index.js';
+
+test('pricing namespace exposes calculator functions', () => {
+  expect(typeof pricing.estimateQuote).toBe('function');
+  expect(typeof pricing.buildPriceMatrix).toBe('function');
+  expect(typeof pricing.resolveVisibleFields).toBe('function');
+  expect(typeof pricing.applyDiscount).toBe('function');
+  expect(typeof pricing.roundHalfEven).toBe('function');
+});

package/src/pricing/index.ts

@@ -0,0 +1,7 @@
+export * from './types.js';
+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';
+export { buildPriceMatrix } from './matrix.js';

package/src/pricing/inventory.test.ts

@@ -0,0 +1,197 @@
+import { resolveUnavailableOptionIds } from './inventory.js';
+import { PricingRules } from './types.js';
+
+// Size (24mm=801, 25mm=802) x Colour (Red=811, Green=812, Blue=813), with
+// per-combination stock. 25mm-Blue = 0; 19mm/24mm-Blue has stock.
+function rules(inventoryUnits: any[]): PricingRules {
+  const opt = (id: number) => ({
+    id, originalId: id, position: id, default: false,
+    variationCost: 0, variationUnitCost: 0,
+    variationCostDiscountGroup: null, variationUnitCostDiscountGroup: null,
+    selectedBy: [],
+  });
+  const f = (id: number, options: number[]): any => ({
+    id, originalId: id, position: 0, fieldType: 2, independent: false,
+    isSelectable: true, selectedBy: [],
+    variationCost: 0, variationUnitCost: 0,
+    variationCostDiscountGroup: null, variationUnitCostDiscountGroup: null,
+    options: options.map(opt),
+  });
+  return {
+    currency: 'AUD', taxPercent: 0,
+    product: { unitPrice: 0, minimumPrice: null, discountGroup: null },
+    fields: [], hasGroups: true, needsInventory: true,
+    groupFields: [f(800, [801, 802]), f(810, [811, 812, 813])],
+    inventoryUnits,
+  };
+}
+
+const units = [
+  { optionIds: [801, 813], quantity: 5 },  // 24mm-Blue: in stock
+  { optionIds: [802, 811], quantity: 7 },  // 25mm-Red: in stock
+  { optionIds: [802, 812], quantity: 7 },  // 25mm-Green: in stock
+  { optionIds: [802, 813], quantity: 0 },  // 25mm-Blue: OUT OF STOCK
+];
+
+test('no inventory units -> nothing unavailable', () => {
+  const r = rules([]);
+  expect(resolveUnavailableOptionIds(r, { fieldValues: {}, groups: [{ quantity: 1, fieldValues: {} }] }).size).toBe(0);
+});
+
+test('with no other selection, an option with stock somewhere is available', () => {
+  const r = rules(units);
+  // Nothing selected: Blue has stock as 24mm-Blue, so not unavailable.
+  const u = resolveUnavailableOptionIds(r, { fieldValues: {}, groups: [{ quantity: 1, fieldValues: {} }] });
+  expect(u.has(813)).toBe(false);
+});
+
+test('25mm makes Blue unavailable but keeps Red/Green available', () => {
+  const r = rules(units);
+  const u = resolveUnavailableOptionIds(r, {
+    fieldValues: {},
+    groups: [{ quantity: 1, fieldValues: { 800: { selectedOptionIds: [802] } } }],
+  });
+  expect(u.has(813)).toBe(true);  // 25mm-Blue = 0 -> Blue disabled
+  expect(u.has(811)).toBe(false); // 25mm-Red ok
+  expect(u.has(812)).toBe(false); // 25mm-Green ok
+});
+
+test('selecting Blue makes 25mm unavailable (combination-aware both directions)', () => {
+  const r = rules(units);
+  const u = resolveUnavailableOptionIds(r, {
+    fieldValues: {},
+    groups: [{ quantity: 1, fieldValues: { 810: { selectedOptionIds: [813] } } }],
+  });
+  expect(u.has(802)).toBe(true);  // 25mm + Blue = 0 -> 25mm disabled
+  expect(u.has(801)).toBe(false); // 24mm + Blue = 5 -> 24mm ok
+});
+
+test('per-group scope: one group selecting 25mm does not disable Blue in another', () => {
+  const r = rules(units);
+  const u = resolveUnavailableOptionIds(r, {
+    fieldValues: {},
+    groups: [{ quantity: 1, fieldValues: { 800: { selectedOptionIds: [801] } } }],
+  });
+  // 24mm selected here -> 24mm-Blue has stock -> Blue available.
+  expect(u.has(813)).toBe(false);
+});
+
+test('omitted inventoryUnits -> nothing unavailable', () => {
+  const r = rules(units);
+  delete (r as any).inventoryUnits;
+  expect(resolveUnavailableOptionIds(r, { fieldValues: {} }).size).toBe(0);
+});
+
+test('non-group product: top-level selections drive availability', () => {
+  const opt = (id: number) => ({
+    id, originalId: null, position: id, default: false,
+    variationCost: 0, variationUnitCost: 0,
+    variationCostDiscountGroup: null, variationUnitCostDiscountGroup: null,
+    selectedBy: [],
+  });
+  const f = (id: number, options: number[]): any => ({
+    id, originalId: id, position: 0, fieldType: 2, independent: true,
+    isSelectable: true, selectedBy: [],
+    variationCost: 0, variationUnitCost: 0,
+    variationCostDiscountGroup: null, variationUnitCostDiscountGroup: null,
+    options: options.map(opt),
+  });
+  const r: PricingRules = {
+    currency: 'AUD', taxPercent: 0,
+    product: { unitPrice: 0, minimumPrice: null, discountGroup: null },
+    hasGroups: false, needsInventory: true,
+    fields: [f(800, [801, 802]), f(810, [811, 813])],
+    groupFields: [],
+    inventoryUnits: [
+      { optionIds: [802, 811], quantity: 7 }, // 25mm-Red
+      { optionIds: [802, 813], quantity: 0 }, // 25mm-Blue OUT
+    ],
+  };
+  const u = resolveUnavailableOptionIds(r, {
+    quantity: 1,
+    fieldValues: { 800: { selectedOptionIds: [802] } },
+  });
+  expect(u.has(813)).toBe(true);  // 25mm-Blue unavailable
+  expect(u.has(811)).toBe(false); // 25mm-Red ok
+});
+
+test('non-inventory options and non-selection field values are ignored', () => {
+  const r = rules(units);
+  // Field 810 option 999 is not in any unit (not tracked); a value-only field
+  // and an undefined selection entry exercise the skip branches.
+  (r.groupFields[1].options as any).push({
+    id: 999, originalId: null, position: 9, default: false,
+    variationCost: 0, variationUnitCost: 0,
+    variationCostDiscountGroup: null, variationUnitCostDiscountGroup: null,
+    selectedBy: [],
+  });
+  const u = resolveUnavailableOptionIds(r, {
+    fieldValues: { 700: { value: 'text' }, 701: undefined as any },
+    groups: [{ quantity: 1, fieldValues: { 800: { selectedOptionIds: [802] }, 810: { selectedOptionIds: [999] } } }],
+  });
+  expect(u.has(999)).toBe(false); // untracked option is always available
+  expect(u.has(813)).toBe(true);  // 25mm-Blue still unavailable
+});
+
+test('undefined top-level fieldValues and group fieldValues are tolerated', () => {
+  const r = rules(units);
+  const u = resolveUnavailableOptionIds(r, {
+    fieldValues: undefined as any,
+    groups: [{ quantity: 1, fieldValues: undefined as any }],
+  });
+  // No selections -> only options with zero stock everywhere would be flagged;
+  // every option here has stock in some combo, so none unavailable.
+  expect(u.size).toBe(0);
+});
+
+test('same field selected at top level and in a group merges selections', () => {
+  const r = rules(units);
+  const u = resolveUnavailableOptionIds(r, {
+    fieldValues: { 800: { selectedOptionIds: [802] } },
+    groups: [{ quantity: 1, fieldValues: { 800: { selectedOptionIds: [802] } } }],
+  });
+  expect(u.has(813)).toBe(true); // 25mm selected (both scopes) -> Blue unavailable
+});
+
+test('unit referencing an unknown option id falls back to the raw id', () => {
+  const r = rules([
+    { optionIds: [802, 813], quantity: 0 },
+    { optionIds: [802, 5555], quantity: 9 }, // 5555 not a known option
+  ]);
+  // 25mm + Blue still 0; the unknown id just never matches a selection.
+  const u = resolveUnavailableOptionIds(r, {
+    fieldValues: {},
+    groups: [{ quantity: 1, fieldValues: { 800: { selectedOptionIds: [802] } } }],
+  });
+  expect(u.has(813)).toBe(true);
+});
+
+test('originalId is canonicalised when matching units', () => {
+  const opt = (id: number, originalId: number | null) => ({
+    id, originalId, position: id, default: false,
+    variationCost: 0, variationUnitCost: 0,
+    variationCostDiscountGroup: null, variationUnitCostDiscountGroup: null,
+    selectedBy: [],
+  });
+  const r: PricingRules = {
+    currency: 'AUD', taxPercent: 0,
+    product: { unitPrice: 0, minimumPrice: null, discountGroup: null },
+    fields: [], hasGroups: true, needsInventory: true,
+    groupFields: [
+      {
+        id: 800, originalId: 800, position: 0, fieldType: 2, independent: false,
+        isSelectable: true, selectedBy: [],
+        variationCost: 0, variationUnitCost: 0,
+        variationCostDiscountGroup: null, variationUnitCostDiscountGroup: null,
+        options: [opt(900, 802)], // cloned option 900 whose original is 802
+      },
+    ],
+    // inventory references the original id 802
+    inventoryUnits: [{ optionIds: [802], quantity: 0 }],
+  };
+  const u = resolveUnavailableOptionIds(r, {
+    fieldValues: {},
+    groups: [{ quantity: 1, fieldValues: {} }],
+  });
+  expect(u.has(900)).toBe(true); // original 802 has 0 stock -> cloned 900 unavailable
+});

package/src/pricing/inventory.ts

@@ -0,0 +1,89 @@
+import { PricingRules, PricingField, Selections } from './types.js';
+
+// 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.py `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: PricingRules,
+  selections: Selections
+): Set<number> {
+  const unavailable = new Set<number>();
+  const units = rules.inventoryUnits || [];
+  if (units.length === 0) return unavailable;
+
+  const allFields: PricingField[] = [...rules.fields, ...rules.groupFields];
+
+  // Canonicalise id/originalId to a single id per option so bundle option ids,
+  // selected ids and inventory unit ids all compare consistently.
+  const canonical = new Map<number, number>();
+  const fieldIdByOption = new Map<number, number>();
+  for (const f of allFields) {
+    for (const o of f.options) {
+      canonical.set(o.id, o.id);
+      fieldIdByOption.set(o.id, f.id);
+      if (o.originalId != null) {
+        canonical.set(o.originalId, o.id);
+        fieldIdByOption.set(o.originalId, f.id);
+      }
+    }
+  }
+  const canon = (id: number): number => (canonical.has(id) ? (canonical.get(id) as number) : id);
+
+  const unitSets = units.map((u) => ({
+    quantity: u.quantity,
+    optionIds: new Set(u.optionIds.map(canon)),
+  }));
+  const inventoryOptionIds = new Set<number>();
+  for (const u of unitSets) {
+    for (const id of u.optionIds) inventoryOptionIds.add(id);
+  }
+
+  // Collect currently-selected, inventory-tracked option ids grouped by field.
+  const selectedByField = new Map<number, Set<number>>();
+  const addSelections = (
+    fieldValues: Record<number, { selectedOptionIds?: number[] }>
+  ) => {
+    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<number>();
+      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; // not inventory-tracked
+      // filter = candidate + selected inventory options from OTHER fields.
+      const filter: number[] = [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;
+}