@happyvertical/smrt-inventory

pnpm add @happyvertical/smrt-inventory

import {
  createStockService,
  InventoryLocationCollection,
} from '@happyvertical/smrt-inventory';
// Catalog shapes (Sku, Product, ...) live in smrt-products. For
// server-side scripts, tests, and SSR runtimes that don't run the Vite
// plugin, import from the /collections subpath.
import { SkuCollection } from '@happyvertical/smrt-products/collections';

const db = { type: 'sqlite', url: 'app.db' };
const skus = await SkuCollection.create({ db });
const locations = await InventoryLocationCollection.create({ db });
const stock = await createStockService({ db });

const widget = await skus.create({
  productId: 'prod-1',
  code: 'WIDGET-001',
  attributes: { finish: 'matte' },
});
await widget.save();

const warehouse = await locations.create({
  code: 'WH-EAST',
  name: 'Warehouse East',
  kind: 'warehouse',
});
await warehouse.save();

// Inbound receipt — +qty available.
await stock.receive(widget.id, warehouse.id, 100, {
  sourceType: 'PurchaseOrder',
  sourceId: po.id,
});

// Reserve against an order — available -> allocated.
// Throws InsufficientStockError if there isn't enough available.
await stock.reserve(widget.id, warehouse.id, 10, {
  sourceType: 'Contract',
  sourceId: order.id,
});

// Cancel a reservation — allocated -> available.
await stock.release(widget.id, warehouse.id, 4);

// Ship — removes from allocated, leaves the building.
await stock.fulfill(widget.id, warehouse.id, 6, {
  sourceType: 'Fulfillment',
  sourceId: shipment.id,
});

// Cycle count caught five extra units — non-zero signed delta.
await stock.adjust(widget.id, warehouse.id, 5, {
  sourceType: 'CycleCount',
  sourceId: count.id,
});

// Move stock between locations — writes transfer_out + transfer_in legs.
await stock.transfer(widget.id, warehouse.id, store.id, 12, {
  sourceType: 'TransferOrder',
  sourceId: xfer.id,
});

// Atomicity across multiple stock calls — e.g. reserve every line of
// an order in one indivisible step. A shortfall on line N rolls back
// lines 1..N-1. Individual methods are already atomic on their own; use
// withTransaction only for cross-call composition.
await stock.withTransaction(async (tx) => {
  for (const line of order.lines) {
    await tx.reserve(line.skuId, line.locationId, line.qty, {
      sourceType: 'Contract',
      sourceId: order.id,
    });
  }
});

import {
  StockLevelCollection,
  StockMovementCollection,
} from '@happyvertical/smrt-inventory';

const levels = await StockLevelCollection.create({ db });
const movements = await StockMovementCollection.create({ db });

// What's on hand at this location across every state?
const here = await levels.findByLocation(warehouse.id);

// Available total for a SKU across all locations?
const availableTotal = await levels.totalForSku(widget.id, 'available');

// What movements were caused by a particular contract?
const audit = await movements.findBySource('Contract', order.id);

import { InsufficientStockError } from '@happyvertical/smrt-inventory';

try {
  await stock.reserve(widget.id, warehouse.id, 9999);
} catch (err) {
  if (err instanceof InsufficientStockError) {
    // err carries skuId, locationId, state, requested, available
    console.log(
      `Only ${err.available} available for ${err.skuId}, requested ${err.requested}`,
    );
  } else {
    throw err;
  }
}

import { createDispatchBus } from '@happyvertical/smrt-core';
import { installInventoryDispatchHandlers } from '@happyvertical/smrt-inventory';

const bus = await createDispatchBus({ db });

// Off by default — opt in explicitly in your smrt.ts.
const handlers = await installInventoryDispatchHandlers({
  dispatchBus: bus,
  db,
  // Per-handler toggles (both default true):
  installContractReserved: true,
  installFulfillmentShipped: true,
});

// In smrt-commerce (or your own code):
await bus.emit('contract:created', {
  contractId: order.id,
  lines: [{ skuId, locationId, qty }],
});

await bus.emit('fulfillment:shipped', {
  fulfillmentId: shipment.id,
  lines: [{ skuId, locationId, qty }],
});

// handlers.dispose() detaches the subscribers (tests / shutdown).

import { withTenant } from '@happyvertical/smrt-tenancy';

await withTenant({ tenantId: 'tenant-a' }, async () => {
  // Every read/write through locations, levels, movements, and the
  // StockService is filtered by tenant_id = 'tenant-a'.
  await stock.receive(widget.id, warehouse.id, 100);
});