Warehouse Receiving Quickstart

mkdir stateset-receiving-example
cd stateset-receiving-example
npm init -y
npm install @stateset/embedded@1.35.1

import assert from 'node:assert/strict';
import { Commerce } from '@stateset/embedded';

const commerce = new Commerce(':memory:');
assert.equal(await commerce.inboundShipments.isSupported(), true);
const supplier = await commerce.purchaseOrders.createSupplier({ name: 'Example supplier' });
const product = await commerce.products.create({ name: 'Ceramic mug', slug: 'ceramic-mug' });
const sku = 'MUG-001';
await commerce.inventory.createItem({ sku, name: 'Ceramic mug', initialQuantity: 0 });
const input = {
  supplierId: supplier.id,
  items: [{ productId: product.id, sku, quantityExpected: '10' }],
};
const shipment = await commerce.inboundShipments.create(input);
assert.equal(shipment.status, 'pending');
assert.equal(shipment.items[0].quantityReceived, '0');
const itemId = shipment.items[0].id;
console.log('Created: pending, received=0 of 10');

const inTransit = await commerce.inboundShipments.markInTransit(shipment.id);
assert.equal(inTransit.status, 'in_transit');
const arrived = await commerce.inboundShipments.markArrived(shipment.id);
assert.equal(arrived.status, 'arrived');
console.log('Arrival recorded: arrived');

const partial = await commerce.inboundShipments.receiveLine(shipment.id, itemId, '4');
assert.equal(partial.status, 'partially_received');
assert.equal(partial.items[0].quantityReceived, '4');
console.log('First receipt: partially_received, received=4 of 10');

await assert.rejects(
  () => commerce.inboundShipments.receiveLine(shipment.id, itemId, '7'),
  { code: 'VALIDATION', message: /would exceed the 10 expected/ },
);
const afterRejection = await commerce.inboundShipments.get(shipment.id);
assert.equal(afterRejection.status, 'partially_received');
assert.equal(afterRejection.items[0].quantityReceived, '4');
console.log('Excess receipt rejected; received quantity is still 4');

const received = await commerce.inboundShipments.receiveLine(shipment.id, itemId, '6');
assert.equal(received.status, 'received');
assert.equal(received.items[0].quantityReceived, '10');
assert.ok(received.receivedAt);
console.log('Final receipt: received, received=10 of 10');

const stock = await commerce.inventory.getStock(sku);
assert.deepEqual(
  [stock.totalOnHand, stock.totalAllocated, stock.totalAvailable],
  ['0', '0', '0'],
);
console.log('Inventory remains: on hand=0, allocated=0, available=0');

// A separate shipment demonstrates cancellation without changing the received one.
const abandoned = await commerce.inboundShipments.create({
  ...input,
  items: [{ ...input.items[0], quantityExpected: '2' }],
});
await commerce.inboundShipments.cancel(abandoned.id);
await assert.rejects(
  () => commerce.inboundShipments.receiveLine(abandoned.id, abandoned.items[0].id, '1'),
  { code: 'VALIDATION', message: /cancelled inbound shipment/ },
);
const cancelled = await commerce.inboundShipments.get(abandoned.id);
assert.equal(cancelled.status, 'cancelled');
assert.equal(cancelled.items[0].quantityReceived, '0');
console.log('Cancelled shipment rejects receipt; received quantity is still 0');

node receiving-demo.mjs

Created: pending, received=0 of 10
Arrival recorded: arrived
First receipt: partially_received, received=4 of 10
Excess receipt rejected; received quantity is still 4
Final receipt: received, received=10 of 10
Inventory remains: on hand=0, allocated=0, available=0
Cancelled shipment rejects receipt; received quantity is still 0