Fulfillment & Shipping

mkdir stateset-shipping-example
cd stateset-shipping-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:');
const customer = await commerce.customers.create({
  email: 'ada@example.com', firstName: 'Ada', lastName: 'Lovelace',
});
const sku = 'MUG-001';
await commerce.inventory.createItem({ sku, name: 'Ceramic mug', initialQuantity: 10 });
const order = await commerce.orders.createExact({
  customerId: customer.id,
  currency: 'USD',
  stockPolicy: 'reject_if_insufficient',
  items: [{ sku, name: 'Ceramic mug', quantity: 2, unitPrice: '12.50' }],
});
const shipment = await commerce.shipments.create({
  orderId: order.id,
  recipientName: 'Example recipient',
  shippingAddress: '123 Example Street, Example City',
  carrier: 'other',
  shippingMethod: 'standard',
});
assert.equal(shipment.orderId, order.id);
assert.equal(shipment.status, 'pending');
console.log('Shipment created: pending');

// Demonstration policy for a single writer, not an engine transaction or lock.
async function recordDelivery(id) {
  const current = await commerce.shipments.get(id);
  if (!current || current.status !== 'shipped') {
    throw new Error('Application policy: only a shipped record can be delivered');
  }
  return commerce.shipments.deliver(id);
}

await assert.rejects(
  () => recordDelivery(shipment.id),
  /Application policy: only a shipped record can be delivered/,
);
assert.equal((await commerce.shipments.get(shipment.id)).status, 'pending');
console.log('Early delivery blocked by application policy; shipment is still pending');

// Simulate carrier handoff with a clearly fictional tracking value.
const shipped = await commerce.shipments.ship(shipment.id, 'DEMO-TRACKING-001');
assert.equal(shipped.status, 'shipped');
const storedShipped = await commerce.shipments.get(shipment.id);
assert.equal(storedShipped.status, 'shipped');
assert.equal(storedShipped.trackingNumber, 'DEMO-TRACKING-001');
console.log('Simulated dispatch: shipped, tracking=DEMO-TRACKING-001');

const delivered = await recordDelivery(shipment.id);
assert.equal(delivered.status, 'delivered');
assert.equal((await commerce.shipments.get(shipment.id)).status, 'delivered');
console.log('Simulated delivery: delivered');

const storedOrder = await commerce.orders.get(order.id);
assert.equal(storedOrder.status, 'pending');
assert.equal(storedOrder.fulfillmentStatus, 'unfulfilled');
assert.equal(storedOrder.paymentStatus, 'pending');
console.log('Order remains: pending, fulfillment=unfulfilled, payment=pending');

const stock = await commerce.inventory.getStock(sku);
assert.deepEqual(
  [stock.totalOnHand, stock.totalAllocated, stock.totalAvailable],
  ['10', '2', '8'],
);
assert.equal(await commerce.shipments.count(), 1);
console.log('Inventory remains: on hand=10, allocated=2, available=8');

node shipping-demo.mjs

Shipment created: pending
Early delivery blocked by application policy; shipment is still pending
Simulated dispatch: shipped, tracking=DEMO-TRACKING-001
Simulated delivery: delivered
Order remains: pending, fulfillment=unfulfilled, payment=pending
Inventory remains: on hand=10, allocated=2, available=8