@happyvertical/smrt-inventory 0.30.0

package/AGENTS.md

@@ -0,0 +1,121 @@
+# @happyvertical/smrt-inventory
+
+Multi-location stock tracking. Strictly industry-neutral — the same primitives serve apparel, furniture, automotive, CPG, electronics, and any other vertical that counts discrete units across locations.
+
+## Models
+
+| Model | Purpose |
+|---|---|
+| _(catalog shapes — `Product`, `Material`, `ProductVariant`, `Sku` — live in `@happyvertical/smrt-products`)_ | Sku is the smallest sellable / countable unit; its `attributes` JSON carries axis-value pins. ProductVariant is the per-product axis declaration. Import either from `@happyvertical/smrt-products` directly. |
+| `InventoryLocation` | Warehouse / factory / retail / in-transit / virtual. Open-ended `kind` string. Optional `placeId` references `@happyvertical/smrt-places`. `conflictColumns: ['code', 'tenant_id']`. |
+| `StockLevel` | Materialized `qty` for a `(skuId, locationId, state)` tuple. Upserted in place. **Mutated only by `StockService`.** States: `available`, `allocated`, `wip`, `qc_hold`, `damaged`. |
+| `StockMovement` | Append-only audit log. Every `StockService` mutation writes one (or two for `transfer`). `sourceType` + `sourceId` carry cross-package attribution. |
+
+All three inventory models (`InventoryLocation`, `StockLevel`, `StockMovement`) use `@TenantScoped({ mode: 'optional' })` + nullable `tenantId` so they can be used either tenant-scoped or globally. The catalog shapes (`Product`, `Material`, `ProductVariant`, `Sku`) live in `@happyvertical/smrt-products` and carry their own tenant decoration there.
+
+## StockService — the only sanctioned way to mutate stock
+
+```typescript
+import { createStockService } from '@happyvertical/smrt-inventory';
+
+const service = await createStockService({ db });
+await service.receive(skuId, locationId, qty, { sourceType, sourceId });
+await service.reserve(skuId, locationId, qty, { sourceType, sourceId });
+await service.release(skuId, locationId, qty, { sourceType, sourceId });
+await service.fulfill(skuId, locationId, qty, { sourceType, sourceId });
+await service.transfer(skuId, fromLocId, toLocId, qty, { sourceType, sourceId });
+await service.adjust(skuId, locationId, delta, { sourceType, sourceId });
+```
+
+| Method | Behavior | Movement reason |
+|---|---|---|
+| `receive` | +qty available — purchase receipt, return, production produce | `receipt` |
+| `reserve` | available → allocated. Throws `InsufficientStockError` on overdraw | `reservation` |
+| `release` | allocated → available (order cancel) | `release` |
+| `fulfill` | -qty allocated. Stock leaves the building | `fulfillment` |
+| `transfer` | move stock between locations (writes two movements) | `transfer_out`, `transfer_in` |
+| `adjust` | signed delta — cycle counts and one-off corrections | `adjustment` |
+
+All methods reject zero / negative / non-finite quantities except `adjust`, which accepts non-zero signed deltas. Negative deltas that would drive a state below zero throw `InsufficientStockError`.
+
+## Opt-in DispatchBus hooks
+
+Off by default. Wire them up explicitly in the application's `smrt.ts`:
+
+```typescript
+import { installInventoryDispatchHandlers } from '@happyvertical/smrt-inventory';
+
+const handlers = await installInventoryDispatchHandlers({
+  dispatchBus: bus,
+  db, // or stockService: existingService
+});
+```
+
+This subscribes to:
+- `contract:created` → calls `service.reserve()` for every line inside one `stockService.withTransaction(...)`, attributed to `('Contract', payload.contractId)`
+- `fulfillment:shipped` → calls `service.fulfill()` for every line inside one `stockService.withTransaction(...)`, attributed to `('Fulfillment', payload.fulfillmentId)`
+
+Both handlers are atomic across lines: a shortfall on line N rolls back lines 1..N-1 so the event is all-or-nothing. Without this guarantee, `DispatchBus` would only log the async handler error and a partially-reserved (or partially-fulfilled) contract would have no compensating event to fix it.
+
+Per-handler toggles: `installContractReserved`, `installFulfillmentShipped`. The `production_order:posted` hook is deliberately not installed here — it depends on the BOM model and ships in `@happyvertical/smrt-manufacturing` (issue #1250).
+
+## Schema migration (Phase 1 release)
+
+The `Sku` model moved out of this package and into `@happyvertical/smrt-products`. Previously it lived in this package's `inventory_skus` table; it now lives in `product_skus` over there.
+
+**Upgrade procedure** for deployed consumers:
+
+1. **Let the framework create the destination table first.** Boot the new version once with `@happyvertical/smrt-products` registered in your `SmrtClassOptions`; the lazy `syncSchema` path will create `product_skus` with the right primary key, NOT NULL, UNIQUE (`code`, `tenant_id`), and indexes — they're derived from the `Sku` model decorators and would be stripped by a raw `CREATE TABLE AS SELECT`.
+
+2. **Idempotently copy rows across.** SQLite + Postgres:
+
+   ```sql
+   BEGIN;
+   INSERT INTO product_skus (
+     id, slug, context, created_at, updated_at,
+     tenant_id, product_id, code, barcode, name,
+     attributes, weight_grams, parent_sku_id, active
+   )
+   SELECT
+     id, slug, context, created_at, updated_at,
+     tenant_id, product_id, code, barcode, name,
+     attributes, weight_grams, parent_sku_id, active
+   FROM inventory_skus
+   WHERE NOT EXISTS (
+     SELECT 1 FROM product_skus p WHERE p.id = inventory_skus.id
+   );
+   COMMIT;
+   ```
+
+3. **Drop the legacy table** once you've verified row counts match:
+
+   ```sql
+   DROP TABLE IF EXISTS inventory_skus;
+   ```
+
+`StockLevel.skuId` and `StockMovement.skuId` carry plain string ids that still resolve to the same rows after the rename, so no inventory data has to move.
+
+## Gotchas
+
+- **Movements are append-only.** The materialized `StockLevel` row is derived state; the `StockMovement` ledger is the source of truth. Never let CRUD UIs expose update/delete on the movement table. If you find yourself wanting to "fix" a movement row, write a compensating `adjust()` call instead.
+- **Never call `StockLevel.create()` or `save()` directly.** Going around `StockService` silently desyncs the audit log and breaks cycle counts.
+- **Cross-industry constraint.** This package's vocabulary stays generic: `InventoryLocation`, `StockLevel`, `StockMovement`. Apparel-specific concepts (`Style`, `Makeup`, `Colorway`, fashion `Season`, tech-pack metadata) and their analogues in furniture / automotive / CPG live in the relevant template package, never here. PRs that introduce industry vocabulary should be rejected.
+- **Cross-package references are plain strings.** `skuId`, `placeId`, `sourceId` — all plain string ids, never `@foreignKey()`. Inventory's stock-motion logic only ever reads StockLevel/StockMovement; it doesn't follow `skuId` back to the catalog's Sku table, so the layering stays loose.
+- **`conflictColumns` include `tenant_id`** on `InventoryLocation` and `StockLevel`. NULL-matching semantics (`(code, NULL) IS NOT DISTINCT FROM (code, NULL)`) are handled by `@happyvertical/sql >= 0.74.0` natively, so two saves with the same `(code, NULL)` tuple correctly merge in place. Pass `nullsDistinct: true` at the sql layer to opt back into NULL-distinct semantics.
+- **Atomic per-method, transactional across composition.** Each `StockService` mutation (`receive` / `reserve` / `release` / `fulfill` / `transfer` / `adjust`) wraps every write in a single `db.transaction(...)` (via `@happyvertical/sql >= 0.74.0`). Partial failure rolls the whole call back — level writes and the matching `StockMovement` audit row commit together or not at all. `transfer` writes both legs (source decrement, destination increment, and both audit rows) inside one tx, so a failure mid-`transfer` is fully reverted.
+  Callers composing multiple `StockService` calls into one logical unit (e.g. consuming materials line-by-line for a production order) should wrap them in `await stockService.withTransaction(async (tx) => { ... })` — `tx` is a tx-bound `StockService` with the same public API; mutation calls inside the callback share one transaction and either all commit or all roll back.
+  If the underlying SQL adapter does not expose `transaction()` (extremely rare — all four built-in `@happyvertical/sql >= 0.74.0` adapters implement it), the service degrades to non-atomic serial writes and emits a one-time `console.warn`.
+- **Concurrent reservations: tightened, not bulletproof.** `@happyvertical/sql >= 0.74.0` serialises null-aware *upserts* via a per-key in-process lock (SQLite) or advisory lock (Postgres). That lock fixed the row-creation race (issue #1246) — two concurrent `create()` calls on the same conflict-column tuple no longer race the underlying `INSERT ... ON CONFLICT`. It does NOT serialise the read-modify-write compound that `reserve` / `fulfill` / `transfer` / `adjust` perform on an existing row: each method reads the current level (`SELECT`), computes the new value in JS, then writes it back (`UPDATE` via `save()` on the loaded row). The whole compound is inside one `db.transaction(...)` from round-3, so the level write and audit row commit together — but two concurrent transactions on the same `(skuId, locationId)` can each see the same starting balance, compute the same decrement, and double-spend. Awaited (serial) calls always behave correctly. Use a job queue (e.g. `@happyvertical/smrt-jobs`) or your own mutex when you need hard atomicity across concurrent callers. The full fix is `SELECT ... FOR UPDATE` inside the same transaction (Postgres) or upgrading the journal mode (SQLite); deferred until we see a real high-contention workload that warrants it.
+
+## Source attribution
+
+Every `StockMovement` carries `sourceType` + `sourceId` so downstream queries can reconstruct "what caused this movement". Conventions used by the built-in dispatch handlers:
+
+| sourceType | Emitter | Note |
+|---|---|---|
+| `Contract` | `smrt-commerce` `contract:created` | All reservation/release/fulfilment legs caused by a contract |
+| `Fulfillment` | `smrt-commerce` `fulfillment:shipped` | Outbound shipment |
+| `PurchaseOrder` | (your code) | Inbound receipt |
+| `CycleCount` | (your code) | Adjustments from physical counts |
+| `TransferOrder` | (your code) | Both legs of a transfer |
+| `ProductionOrder` | `smrt-manufacturing` (issue #1250) | Materials consumed + finished goods produced |

package/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright <2025> <Happy Vertical Corporation>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,213 @@
+# @happyvertical/smrt-inventory
+
+Multi-location stock tracking for the SMRT framework. Strictly industry-neutral — the same primitives serve apparel, furniture, automotive, CPG, electronics, and any other vertical that counts discrete units across locations.
+
+## Installation
+
+```bash
+pnpm add @happyvertical/smrt-inventory
+```
+
+## Usage
+
+### Set up SKUs, locations, and a stock service
+
+```typescript
+import {
+  createStockService,
+  InventoryLocationCollection,
+} from '@happyvertical/smrt-inventory';
+// The `@happyvertical/smrt-products` root entry pulls in Vite virtual
+// modules (`@smrt/client` etc.) and won't resolve under plain Node /
+// tsx. Import from the `/collections` subpath for server-side scripts,
+// tests, and SSR runtimes that don't run the Vite plugin.
+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',
+  barcode: '0123456789012',
+  attributes: { finish: 'matte' },
+});
+await widget.save();
+
+const warehouse = await locations.create({
+  code: 'WH-EAST',
+  name: 'Warehouse East',
+  kind: 'warehouse',
+});
+await warehouse.save();
+```
+
+### Move stock through its lifecycle
+
+Every method writes one (or two, for transfers) `StockMovement` audit rows so the ledger stays in lockstep with the materialized levels.
+
+```typescript
+// 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,
+});
+
+// Ship — removes from allocated, leaves the building.
+await stock.fulfill(widget.id!, warehouse.id!, 10, {
+  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,
+});
+```
+
+### Query balances and the audit log
+
+```typescript
+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!);
+
+// What's the 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);
+```
+
+### Catch the insufficient-stock error
+
+```typescript
+import { InsufficientStockError } from '@happyvertical/smrt-inventory';
+
+try {
+  await stock.reserve(widget.id!, warehouse.id!, 9999);
+} catch (err) {
+  if (err instanceof InsufficientStockError) {
+    console.log(
+      `Only ${err.available} available for ${err.skuId} at ${err.locationId}, requested ${err.requested}`,
+    );
+  } else {
+    throw err;
+  }
+}
+```
+
+### Multi-tenancy
+
+The three inventory models (`InventoryLocation`, `StockLevel`, `StockMovement`) use `@TenantScoped({ mode: 'optional' })` with a nullable `tenantId`. The catalog shapes (`Sku`, `Product`, `ProductVariant`, `Material`) live in `@happyvertical/smrt-products` and carry their own tenant decoration there; the cross-package id refs flow through unchanged. Wrap mutations in `withTenant()` from `@happyvertical/smrt-tenancy` to scope queries automatically.
+
+```typescript
+import { withTenant } from '@happyvertical/smrt-tenancy';
+
+await withTenant({ tenantId: 'tenant-a' }, async () => {
+  // Every read/write through skus, locations, levels, movements, and the
+  // StockService is filtered by tenant_id = 'tenant-a'.
+  await stock.receive(widget.id!, warehouse.id!, 100);
+});
+```
+
+### Opt-in DispatchBus wiring
+
+The package ships handlers that bridge `contract:created` → `reserve()` and `fulfillment:shipped` → `fulfill()`. Off by default; install them explicitly in your `smrt.ts` to enable automatic stock motion:
+
+```typescript
+import { createDispatchBus } from '@happyvertical/smrt-core';
+import { installInventoryDispatchHandlers } from '@happyvertical/smrt-inventory';
+
+const bus = await createDispatchBus({ db });
+const handlers = await installInventoryDispatchHandlers({
+  dispatchBus: bus,
+  db,
+});
+
+// In smrt-commerce (or your own code):
+await bus.emit('contract:created', {
+  contractId: order.id,
+  lines: [{ skuId, locationId, qty }],
+});
+
+// Later, on shipment:
+await bus.emit('fulfillment:shipped', {
+  fulfillmentId: shipment.id,
+  lines: [{ skuId, locationId, qty }],
+});
+```
+
+Per-handler toggles (`installContractReserved`, `installFulfillmentShipped`) let consumers pick exactly the signals they care about. The `production_order:posted` handler is intentionally *not* installed here; that bridge lives in `@happyvertical/smrt-manufacturing`.
+
+## API
+
+### Models
+
+| Export | Description |
+|---|---|
+| `InventoryLocation` | Physical or virtual stocking site with open-ended `kind`. |
+| `StockLevel` | Materialized `(skuId, locationId, state) → qty` row. **Never mutate directly — use `StockService`.** |
+| `StockMovement` | Append-only audit row. One per mutation; two for transfers. |
+
+### Collections
+
+| Export | Description |
+|---|---|
+| `InventoryLocationCollection` | `findByCode`, `findByKind`, `findByPlace`, `findActive` |
+| `StockLevelCollection` | `getLevel`, `findBySku`, `findByLocation`, `totalForSku`, `totalForLocation` |
+| `StockMovementCollection` | `findBySku`, `findByLocation`, `findBySource`, `findByReason` |
+
+All catalog shapes (`Product`, `Material`, `ProductVariant`, `Sku`) live in [`@happyvertical/smrt-products`](../products). This package adds the stock-motion layer (`InventoryLocation`, `StockLevel`, `StockMovement`, `StockService`) on top.
+
+### Service
+
+| Export | Description |
+|---|---|
+| `StockService` | The only sanctioned mutation surface. Six methods: `receive`, `reserve`, `release`, `fulfill`, `transfer`, `adjust`. |
+| `createStockService({ db })` | Convenience factory. |
+| `InsufficientStockError` | Thrown by `reserve` / `fulfill` / `transfer` / negative `adjust` when stock would go negative. Carries `skuId`, `locationId`, `state`, `requested`, `available`. |
+| `installInventoryDispatchHandlers({ dispatchBus, db })` | Opt-in DispatchBus wiring for `contract:created` and `fulfillment:shipped`. |
+
+### Types
+
+| Export | Description |
+|---|---|
+| `StockState` | `'available' \| 'allocated' \| 'wip' \| 'qc_hold' \| 'damaged'` |
+| `InventoryLocationKind` | Open-ended classifier string |
+| `StockMovementReason` | Canonical reason vocabulary (`'receipt'`, `'reservation'`, `'release'`, `'fulfillment'`, `'transfer_out'`, `'transfer_in'`, `'adjustment'`, `'production_consume'`, `'production_produce'`) plus free-form strings |
+
+## Dependencies
+
+| Package | Purpose |
+|---|---|
+| `@happyvertical/smrt-core` | SmrtObject / SmrtCollection / DispatchBus |
+| `@happyvertical/smrt-tenancy` | Optional tenant scoping |
+| `@happyvertical/sql` | Database adapter |
+
+## License
+
+MIT