StateSet API Docs

Model a kit containing two mugs, then record production of three kits: one in the first batch and two in the second. Read the work order after each batch and inspect component and finished stock independently. This complete example uses @stateset/embedded 1.35.1 with a temporary local database. No API key, production equipment, or external warehouse service is required.

Work-order completion records production progress. In this example it neither consumes mug inventory nor adds finished kits to inventory. Those movements require a separate process with its own verification and recovery behavior.

Prerequisites

Use Node.js 20.20.0+ and npm 10+:

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

See SDK installation for native-module troubleshooting.

Run the complete example

Save this as manufacturing-demo.mjs:

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

const commerce = new Commerce(':memory:');
const product = await commerce.products.create({ name: 'Mug kit', slug: 'mug-kit' });
const componentSku = 'MUG-001';
const finishedSku = 'KIT-001';
await commerce.inventory.createItem({
  sku: componentSku, name: 'Ceramic mug', initialQuantity: 20,
});
await commerce.inventory.createItem({
  sku: finishedSku, name: 'Mug kit', initialQuantity: 0,
});

const bom = await commerce.bom.create({
  name: 'Two-mug kit', productId: product.id, revision: 'A',
});
assert.equal(bom.status, 'draft');
await commerce.bom.addComponent(bom.id, {
  componentSku, name: 'Ceramic mug', quantity: 2, unitOfMeasure: 'each',
});
const components = await commerce.bom.getComponents(bom.id);
assert.equal(components.length, 1);
assert.equal(components[0].componentSku, componentSku);
assert.equal(components[0].quantity, 2);
await commerce.bom.activate(bom.id);
const activeBom = await commerce.bom.get(bom.id);
assert.equal(activeBom.status, 'active');
assert.equal(activeBom.revision, 'A');
console.log('BOM active: revision A, 2 mugs per kit');

const workOrder = await commerce.workOrders.create({
  productId: product.id, bomId: bom.id, quantityToBuild: 3,
});
assert.equal(workOrder.status, 'planned');
assert.equal(workOrder.quantityCompleted, 0);
assert.equal(workOrder.bomId, bom.id);
console.log('Work order planned: target=3, completed=0');

await commerce.workOrders.start(workOrder.id);
assert.equal((await commerce.workOrders.get(workOrder.id)).status, 'in_progress');
console.log('Work order started: in_progress');

await commerce.workOrders.complete(workOrder.id, 1);
const partial = await commerce.workOrders.get(workOrder.id);
assert.equal(partial.status, 'partially_completed');
assert.equal(partial.quantityCompleted, 1);
console.log('First batch: partially_completed, completed=1');

// The argument is the additional quantity in this batch, not the cumulative total.
await commerce.workOrders.complete(workOrder.id, 2);
const completed = await commerce.workOrders.get(workOrder.id);
assert.equal(completed.status, 'completed');
assert.equal(completed.quantityCompleted, 3);
assert.equal(completed.quantityToBuild, 3);
console.log('Second batch: completed, completed=3');

const componentStock = await commerce.inventory.getStock(componentSku);
const finishedStock = await commerce.inventory.getStock(finishedSku);
assert.deepEqual(
  [componentStock.totalOnHand, componentStock.totalAllocated, componentStock.totalAvailable],
  ['20', '0', '20'],
);
assert.deepEqual(
  [finishedStock.totalOnHand, finishedStock.totalAllocated, finishedStock.totalAvailable],
  ['0', '0', '0'],
);
assert.equal(await commerce.workOrders.count(), 1);
console.log('Inventory unchanged: mugs=20, finished kits=0, allocated=0');

node manufacturing-demo.mjs

Success: all assertions pass and the output is:

BOM active: revision A, 2 mugs per kit
Work order planned: target=3, completed=0
Work order started: in_progress
First batch: partially_completed, completed=1
Second batch: completed, completed=3
Inventory unchanged: mugs=20, finished kits=0, allocated=0

Understand the records and quantities

Record or value	Meaning in this example
Product ID	Identifies the kit product used by the BOM and work order
BOM ID and revision	Identify the component definition selected for production
Component SKU	Identifies the mug inventory item referenced by the BOM line
Finished SKU	Identifies the separately created kit inventory item; this example does not establish automatic product-to-stock posting
Work-order ID	Used to start production, record batches, and read progress
`quantityToBuild`	Planned number of kits: three
`complete(id, quantity)`	Adds the quantity reported for this batch
`quantityCompleted`	Cumulative progress: zero, then one, then three

The component requirement for this example is six mugs: two per kit times three kits. That calculation describes the plan; it is not evidence that six mugs were reserved or consumed. The inventory assertions verify that no such movements happened in this program. Do not pass the cumulative total to the second completion call. The demonstrated calls add one and then two; passing three after the first batch would report another three units.

Define the production policy before automating

The example follows planned → in_progress → partially_completed → completed. This is the path it exercises, not a promise that the SDK rejects every invalid transition. In the published version, start accepts a cancelled work order. Enforce your allowed transitions and permissions in the application rather than assuming a cancelled job cannot restart. Before recording real production, verify the selected product, approved BOM revision, units of measure, material availability, accepted output count, and any required quality checks. Decide which system owns scrap, rework, lots/serials, and production evidence. The published Node WorkOrderOutput is a progress summary; it does not supply all of that operational evidence. Keep the BOM identity and revision with the production record. Do not treat the existence of an active BOM as proof that a specific production run passed review or that its materials are available.

Connect production to inventory

Choose the process that consumes components and receives finished goods, and retain its movement IDs alongside the work-order and batch IDs. Read both sides after processing. For this demonstration plan, a full run would require accounting for six mugs and three kits. Real counts can differ because of scrap or rework; record observed quantities under the configured policy rather than deriving all movements from the planned quantity. The inventory quickstart demonstrates adjustments, reservations, and read-back. Combining several adjustments with workOrders.complete does not make those calls an atomic manufacturing transaction. Design recovery for each partial outcome:

Observed outcome	What to reconcile before more writes
Production recorded, stock unchanged	Whether the inventory-posting job ran and which movement IDs it produced
Components consumed, finished stock missing	The receipt outcome and any quality hold, scrap, or rework
Stock posted, work-order response lost	The original batch outcome and cumulative production before another completion call
Duplicate production event	The stored event identity and all previously recorded progress and movements

Use connect your operation to map manufacturing, warehouse, and accounting ownership. Labor costing, machine telemetry, and quality-release integrations are outside this example.

Handle retries and concurrent writers

The published Node completion signature has no idempotency-key parameter, and completion quantities accumulate. Retrying a batch after a lost response can double-count production. Retain a durable batch/event identity, the work-order ID, additional quantity, and observed outcome in your integration. Read the work order and reconcile the original batch evidence before replaying a completion. A cumulative quantity alone may be ambiguous when several workers report progress. Coordinate writers for each work order; a separate read followed by a write is not an atomic guard. See error handling and retries and the integration test plan before unattended operation.

Give an agent a production task

Start with a read-only task: provide the work-order ID, BOM ID, and relevant inventory SKUs; ask for the target quantity, completed quantity, state, BOM components, and separately observed stock. Require the agent to identify missing material, quality, or movement evidence. For a write, specify the allowed transition, batch identity, additional accepted quantity, and authorization. Permission to record progress does not authorize changing the BOM, adjusting inventory, or releasing a quality hold. Discover the installed tool schemas rather than guessing MCP names from Node methods. Follow the agent operating procedure. Report production progress and inventory-posting status separately, with the IDs and read-back results supporting each outcome.

Troubleshooting

Symptom	Check or next step
Work order completed but finished stock is zero	Expected here; inspect the separate finished-goods posting process
Component stock remains unchanged	Inspect material reservation/consumption; the BOM is a definition, not a movement
Completed quantity too high after a retry	Reconcile duplicate batch events and additional versus cumulative quantities
Cancelled job starts again	Enforce the configured transition policy before calling `start`
Wrong component quantities	Verify BOM ID/revision, units of measure, and per-kit versus batch quantities
Data disappears after exit	`:memory:` is temporary; use a file-backed database for persistent state

Next steps

Inventory quickstart: verify stock independently from production.
Warehouse receiving: inspect inbound progress and stock-posting boundaries.
Supplier and purchasing: create and approve a purchase order for materials.

Overview

Quickstarts

End-to-end

Commerce Workflows

Order Management

Returns & Warranties

Supply Chain

Agent Development

Knowledge & RAG

Response Features

Advanced Features

Integrations

Commerce Network

Self-Hosted

Best Practices

E-commerce Workflows

Manufacturing Quickstart

Prerequisites

Run the complete example

Understand the records and quantities

Define the production policy before automating

Connect production to inventory

Handle retries and concurrent writers

Give an agent a production task

Troubleshooting

Next steps

​Prerequisites

​Run the complete example

​Understand the records and quantities

​Define the production policy before automating

​Connect production to inventory

​Handle retries and concurrent writers

​Give an agent a production task

​Troubleshooting

​Next steps

Prerequisites

Run the complete example

Understand the records and quantities

Define the production policy before automating

Connect production to inventory

Handle retries and concurrent writers

Give an agent a production task

Troubleshooting

Next steps