@happyvertical/smrt-inventory 0.30.0

package/dist/index.js

@@ -0,0 +1,922 @@
+import { ObjectRegistry, field, smrt, SmrtObject, SmrtCollection, resolveDatabase } from "@happyvertical/smrt-core";
+import { tenantId, TenantScoped } from "@happyvertical/smrt-tenancy";
+import { createLogger } from "@happyvertical/logger";
+ObjectRegistry.registerPackageManifest(
+  new URL("./manifest.json", import.meta.url)
+);
+var __defProp$2 = Object.defineProperty;
+var __getOwnPropDesc$2 = Object.getOwnPropertyDescriptor;
+var __decorateClass$2 = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc$2(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+  if (kind && result) __defProp$2(target, key, result);
+  return result;
+};
+let InventoryLocation = class extends SmrtObject {
+  tenantId = null;
+  code = "";
+  /** Display name for UIs. */
+  name = "";
+  /**
+   * Open-ended classifier (`'warehouse'`, `'factory'`, `'retail'`,
+   * `'in_transit'`, `'virtual'`, or anything else your domain needs).
+   * The framework never branches on this value.
+   */
+  kind = "warehouse";
+  /**
+   * Optional plain-string reference to a `Place.id` in
+   * `@happyvertical/smrt-places`. Cross-package id; intentionally not a
+   * `@foreignKey()` so this package can be used without `smrt-places`
+   * installed.
+   */
+  placeId = "";
+  /** Soft-active flag — inactive locations stay queryable for history. */
+  active = true;
+  constructor(options = {}) {
+    super(options);
+    if (options.tenantId !== void 0) this.tenantId = options.tenantId;
+    if (options.code !== void 0) this.code = options.code;
+    if (options.name !== void 0) this.name = options.name;
+    if (options.kind !== void 0) this.kind = options.kind;
+    if (options.placeId !== void 0) this.placeId = options.placeId;
+    if (options.active !== void 0) this.active = options.active;
+  }
+};
+__decorateClass$2([
+  tenantId({ nullable: true })
+], InventoryLocation.prototype, "tenantId", 2);
+__decorateClass$2([
+  field({ required: true })
+], InventoryLocation.prototype, "code", 2);
+InventoryLocation = __decorateClass$2([
+  TenantScoped({ mode: "optional" }),
+  smrt({
+    tableName: "inventory_locations",
+    conflictColumns: ["code", "tenant_id"],
+    api: { include: ["list", "get", "create", "update"] },
+    mcp: { include: ["list", "get"] },
+    cli: true
+  })
+], InventoryLocation);
+class InventoryLocationCollection extends SmrtCollection {
+  static _itemClass = InventoryLocation;
+  /**
+   * Look up a location by its tenant-scoped `code`. Returns `null` when
+   * no row matches.
+   */
+  async findByCode(code) {
+    const matches = await this.list({ where: { code }, limit: 1 });
+    return matches[0] ?? null;
+  }
+  /**
+   * Find every location classified as the given kind (`'warehouse'`,
+   * `'factory'`, `'retail'`, `'in_transit'`, …).
+   */
+  async findByKind(kind) {
+    return this.list({ where: { kind }, orderBy: "code ASC" });
+  }
+  /**
+   * Find every location linked to a particular `Place.id` from
+   * `@happyvertical/smrt-places`. Returns an empty array when no row
+   * references the place.
+   */
+  async findByPlace(placeId) {
+    if (!placeId) return [];
+    return this.list({ where: { placeId }, orderBy: "code ASC" });
+  }
+  /** Find every active location, optionally narrowed by kind. */
+  async findActive(kind) {
+    const where = { active: true };
+    if (kind) where.kind = kind;
+    return this.list({ where, orderBy: "code ASC" });
+  }
+}
+var __defProp$1 = Object.defineProperty;
+var __getOwnPropDesc$1 = Object.getOwnPropertyDescriptor;
+var __decorateClass$1 = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc$1(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+  if (kind && result) __defProp$1(target, key, result);
+  return result;
+};
+let StockLevel = class extends SmrtObject {
+  tenantId = null;
+  skuId = "";
+  locationId = "";
+  state = "available";
+  qty = 0;
+  constructor(options = {}) {
+    super(options);
+    if (options.tenantId !== void 0) this.tenantId = options.tenantId;
+    if (options.skuId !== void 0) this.skuId = options.skuId;
+    if (options.locationId !== void 0) this.locationId = options.locationId;
+    if (options.state !== void 0) this.state = options.state;
+    if (options.qty !== void 0) this.qty = options.qty;
+  }
+};
+__decorateClass$1([
+  tenantId({ nullable: true })
+], StockLevel.prototype, "tenantId", 2);
+__decorateClass$1([
+  field({ required: true })
+], StockLevel.prototype, "skuId", 2);
+__decorateClass$1([
+  field({ required: true })
+], StockLevel.prototype, "locationId", 2);
+__decorateClass$1([
+  field({ required: true })
+], StockLevel.prototype, "state", 2);
+__decorateClass$1([
+  field({ type: "decimal" })
+], StockLevel.prototype, "qty", 2);
+StockLevel = __decorateClass$1([
+  TenantScoped({ mode: "optional" }),
+  smrt({
+    tableName: "inventory_stock_levels",
+    conflictColumns: ["sku_id", "location_id", "state", "tenant_id"],
+    // StockLevel is materialized state, written only by StockService.
+    // Mirror the read-only api/mcp posture on the CLI — `cli: true` would
+    // generate create/update/delete subcommands that let a CLI user
+    // mutate `qty` (or delete a row) without writing a paired
+    // StockMovement, silently desyncing the audit ledger from the
+    // materialized balance. The Gotchas section in CLAUDE.md spells out
+    // the "never call StockLevel.save() directly" rule; the CLI must
+    // follow the same constraint.
+    api: { include: ["list", "get"] },
+    mcp: { include: ["list", "get"] },
+    cli: { include: ["list", "get"] }
+  })
+], StockLevel);
+class StockLevelCollection extends SmrtCollection {
+  static _itemClass = StockLevel;
+  /**
+   * Fetch the level row for a `(skuId, locationId, state)` tuple, or
+   * `null` when the row has never been written. State defaults to
+   * `'available'` because that is the common case (selling / picking
+   * decisions are driven by available stock).
+   */
+  async getLevel(skuId, locationId, state = "available") {
+    const matches = await this.list({
+      where: { skuId, locationId, state },
+      limit: 1
+    });
+    return matches[0] ?? null;
+  }
+  /**
+   * Return every level row for the given SKU across all locations and
+   * states. Useful for "where is this SKU?" admin screens.
+   */
+  async findBySku(skuId) {
+    return this.list({ where: { skuId } });
+  }
+  /**
+   * Return every level row at the given location. Useful for "what is
+   * in this warehouse?" reports.
+   */
+  async findByLocation(locationId) {
+    return this.list({ where: { locationId } });
+  }
+  /**
+   * Sum `qty` across all level rows for the given SKU. Pass `state` to
+   * narrow the sum to one logical state (e.g. only `available`);
+   * omit it for grand total across all states.
+   */
+  async totalForSku(skuId, state) {
+    const where = { skuId };
+    if (state) where.state = state;
+    const levels = await this.list({ where });
+    return levels.reduce((sum, row) => sum + Number(row.qty ?? 0), 0);
+  }
+  /**
+   * Sum `qty` across all level rows at the given location, optionally
+   * narrowed by state.
+   */
+  async totalForLocation(locationId, state) {
+    const where = { locationId };
+    if (state) where.state = state;
+    const levels = await this.list({ where });
+    return levels.reduce((sum, row) => sum + Number(row.qty ?? 0), 0);
+  }
+}
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __decorateClass = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+  if (kind && result) __defProp(target, key, result);
+  return result;
+};
+let StockMovement = class extends SmrtObject {
+  tenantId = null;
+  skuId = "";
+  locationId = "";
+  /**
+   * Origin state for transitions (e.g. `available` → `allocated` for a
+   * reservation). `null` indicates "no origin" — used when stock enters
+   * the system fresh via {@link StockService.receive} or production.
+   */
+  fromState = null;
+  /**
+   * Destination state. `null` indicates "no destination" — used for
+   * fulfilment, where stock leaves the building entirely.
+   */
+  toState = null;
+  qty = 0;
+  reasonCode = "adjustment";
+  /**
+   * Cross-package attribution tag — e.g. `'Contract'`, `'Fulfillment'`,
+   * `'ProductionOrder'`, `'CycleCount'`. The package writing the
+   * movement decides what tag makes sense; readers can group by
+   * `(sourceType, sourceId)` to reconstruct "what caused this".
+   */
+  sourceType = "";
+  /**
+   * Cross-package id of the row that caused this movement. Plain string;
+   * the framework never dereferences it.
+   */
+  sourceId = "";
+  /** Optional free-form note shown in audit UIs. */
+  note = "";
+  /**
+   * When the movement happened. Set to `now` at write time; explicit
+   * values are allowed when back-dating an import.
+   */
+  occurredAt = /* @__PURE__ */ new Date();
+  constructor(options = {}) {
+    super(options);
+    if (options.tenantId !== void 0) this.tenantId = options.tenantId;
+    if (options.skuId !== void 0) this.skuId = options.skuId;
+    if (options.locationId !== void 0) this.locationId = options.locationId;
+    if (options.fromState !== void 0) this.fromState = options.fromState;
+    if (options.toState !== void 0) this.toState = options.toState;
+    if (options.qty !== void 0) this.qty = options.qty;
+    if (options.reasonCode !== void 0) this.reasonCode = options.reasonCode;
+    if (options.sourceType !== void 0) this.sourceType = options.sourceType;
+    if (options.sourceId !== void 0) this.sourceId = options.sourceId;
+    if (options.note !== void 0) this.note = options.note;
+    if (options.occurredAt !== void 0) {
+      this.occurredAt = options.occurredAt instanceof Date ? options.occurredAt : new Date(options.occurredAt);
+    }
+  }
+};
+__decorateClass([
+  tenantId({ nullable: true })
+], StockMovement.prototype, "tenantId", 2);
+__decorateClass([
+  field({ required: true })
+], StockMovement.prototype, "skuId", 2);
+__decorateClass([
+  field({ required: true })
+], StockMovement.prototype, "locationId", 2);
+__decorateClass([
+  field({ type: "decimal" })
+], StockMovement.prototype, "qty", 2);
+__decorateClass([
+  field({ required: true })
+], StockMovement.prototype, "reasonCode", 2);
+StockMovement = __decorateClass([
+  TenantScoped({ mode: "optional" }),
+  smrt({
+    tableName: "inventory_stock_movements",
+    // Append-only: the natural key is the surrogate id, so updates can
+    // never collide on conflictColumns. Setting `id` explicitly here
+    // documents the intent and prevents future contributors from
+    // accidentally adding a "domain natural key" that would let upserts
+    // overwrite history.
+    conflictColumns: ["id"],
+    // Movements are an audit log — never mutate or delete via generated
+    // CRUD. Reads are fine for reporting and admin tooling. CLI follows
+    // the same posture as api/mcp; `cli: true` would generate
+    // create/update/delete subcommands that could rewrite or remove
+    // audit rows from the shell, defeating the append-only invariant
+    // documented in CLAUDE.md.
+    api: { include: ["list", "get"] },
+    mcp: { include: ["list", "get"] },
+    cli: { include: ["list", "get"] }
+  })
+], StockMovement);
+class StockMovementCollection extends SmrtCollection {
+  static _itemClass = StockMovement;
+  /**
+   * Return every movement for the given SKU, newest first. Useful for a
+   * per-SKU audit trail.
+   */
+  async findBySku(skuId) {
+    return this.list({ where: { skuId }, orderBy: "occurredAt DESC" });
+  }
+  /**
+   * Return every movement at the given location, newest first. Useful
+   * for a per-warehouse audit trail.
+   */
+  async findByLocation(locationId) {
+    return this.list({
+      where: { locationId },
+      orderBy: "occurredAt DESC"
+    });
+  }
+  /**
+   * Return every movement attributed to the given upstream source — for
+   * example `findBySource('Contract', contract.id)` returns every
+   * movement caused by the reservation/fulfilment/release of that
+   * contract. Newest first.
+   */
+  async findBySource(sourceType, sourceId) {
+    return this.list({
+      where: { sourceType, sourceId },
+      orderBy: "occurredAt DESC"
+    });
+  }
+  /**
+   * Return every movement with the given reason code (`'receipt'`,
+   * `'reservation'`, `'adjustment'`, …). Newest first.
+   */
+  async findByReason(reasonCode) {
+    return this.list({
+      where: { reasonCode },
+      orderBy: "occurredAt DESC"
+    });
+  }
+}
+const logger$1 = createLogger({ level: "info" });
+class InsufficientStockError extends Error {
+  constructor(skuId, locationId, state, requested, available) {
+    super(
+      `Insufficient stock: sku=${skuId} location=${locationId} state=${state} requested=${requested} available=${available}`
+    );
+    this.skuId = skuId;
+    this.locationId = locationId;
+    this.state = state;
+    this.requested = requested;
+    this.available = available;
+  }
+  skuId;
+  locationId;
+  state;
+  requested;
+  available;
+  name = "InsufficientStockError";
+}
+class StockService {
+  constructor(db, levels, movements, locations, inTransaction = false) {
+    this.db = db;
+    this.levels = levels;
+    this.movements = movements;
+    this.locations = locations;
+    this.inTransaction = inTransaction;
+  }
+  db;
+  levels;
+  movements;
+  locations;
+  inTransaction;
+  /** Internal factory — prefer {@link createStockService}. */
+  static async create(options) {
+    const resolved = await resolveDatabase(options.db);
+    const [levels, movements, locations] = await Promise.all([
+      StockLevelCollection.create({ db: resolved }),
+      StockMovementCollection.create({ db: resolved }),
+      InventoryLocationCollection.create({ db: resolved })
+    ]);
+    return new StockService(
+      resolved,
+      levels,
+      movements,
+      locations
+    );
+  }
+  /**
+   * Run `work` inside a single database transaction with a tx-bound
+   * {@link StockService} instance. All mutation calls on `tx` commit
+   * atomically when `work` resolves and roll back if it throws.
+   *
+   * Use this when you need atomicity ACROSS multiple stock-service
+   * calls — e.g. consuming materials for every line of a production
+   * order in `@happyvertical/smrt-manufacturing`'s `ProductionService`,
+   * or a custom workflow that reserves + fulfills + writes a custom
+   * audit comment in one indivisible step. Individual mutation methods
+   * (`receive`, `reserve`, etc.) are already atomic on their own — you
+   * only need `withTransaction` for cross-call composition.
+   *
+   * Nesting is safe: calling `tx.withTransaction(...)` inside an
+   * already-tx-bound callback simply runs the inner `work` on the same
+   * transaction without opening a savepoint.
+   *
+   * When the underlying adapter does not expose `transaction()`, falls
+   * through to a serial run on the regular collections with a one-time
+   * warning. All four built-in adapters in `@happyvertical/sql >= 0.74.0`
+   * support it; only test stubs would hit this branch.
+   */
+  async withTransaction(work) {
+    if (this.inTransaction) return work(this);
+    const underlying = this.levels.db;
+    if (typeof underlying?.transaction !== "function") {
+      warnNonTransactional();
+      return work(this);
+    }
+    return underlying.transaction(async (txDb) => {
+      const [levels, movements, locations] = await Promise.all([
+        StockLevelCollection.create({ db: txDb }),
+        StockMovementCollection.create({ db: txDb }),
+        InventoryLocationCollection.create({ db: txDb })
+      ]);
+      const tx = new StockService(
+        txDb,
+        levels,
+        movements,
+        locations,
+        /* inTransaction */
+        true
+      );
+      return work(tx);
+    });
+  }
+  /**
+   * Internal: run a single-method mutation in a transaction. If we're
+   * already inside one (the instance was handed to a `withTransaction`
+   * callback), reuse it; otherwise open a fresh one.
+   */
+  async runAtomically(work) {
+    if (this.inTransaction) {
+      return work({ levels: this.levels, movements: this.movements });
+    }
+    return this.withTransaction(
+      async (tx) => work({ levels: tx.levels, movements: tx.movements })
+    );
+  }
+  /**
+   * Add `qty` to available stock at the given location. Used for
+   * purchase-order receipts, customer returns going back into available
+   * inventory, and the "produce" leg of a production order.
+   */
+  async receive(skuId, locationId, qty, options = {}) {
+    assertPositiveQty(qty, "receive");
+    await this.runAtomically(async (tx) => {
+      await adjustLevel(tx.levels, {
+        skuId,
+        locationId,
+        state: "available",
+        delta: qty
+      });
+      await writeMovement(tx.movements, {
+        skuId,
+        locationId,
+        fromState: null,
+        toState: "available",
+        qty,
+        reasonCode: options.reasonCode ?? "receipt",
+        sourceType: options.sourceType,
+        sourceId: options.sourceId,
+        note: options.note
+      });
+    });
+  }
+  /**
+   * Move `qty` from `available` to `allocated` at the given location.
+   * Throws {@link InsufficientStockError} if available stock would go
+   * negative.
+   */
+  async reserve(skuId, locationId, qty, options = {}) {
+    assertPositiveQty(qty, "reserve");
+    await this.runAtomically(async (tx) => {
+      await transitionState(tx, {
+        skuId,
+        locationId,
+        fromState: "available",
+        toState: "allocated",
+        qty,
+        reasonCode: options.reasonCode ?? "reservation",
+        sourceType: options.sourceType,
+        sourceId: options.sourceId,
+        note: options.note
+      });
+    });
+  }
+  /**
+   * Move `qty` from `allocated` back to `available`. Used when a
+   * reservation is cancelled and the previously-reserved stock should
+   * go back into the available pool.
+   */
+  async release(skuId, locationId, qty, options = {}) {
+    assertPositiveQty(qty, "release");
+    await this.runAtomically(async (tx) => {
+      await transitionState(tx, {
+        skuId,
+        locationId,
+        fromState: "allocated",
+        toState: "available",
+        qty,
+        reasonCode: options.reasonCode ?? "release",
+        sourceType: options.sourceType,
+        sourceId: options.sourceId,
+        note: options.note
+      });
+    });
+  }
+  /**
+   * Remove `qty` from `allocated` at the given location. Stock leaves
+   * the building entirely (shipped, picked up, consumed). Throws
+   * {@link InsufficientStockError} if allocated stock would go negative.
+   */
+  async fulfill(skuId, locationId, qty, options = {}) {
+    assertPositiveQty(qty, "fulfill");
+    await this.runAtomically(async (tx) => {
+      await assertAvailable(tx.levels, skuId, locationId, "allocated", qty);
+      await adjustLevel(tx.levels, {
+        skuId,
+        locationId,
+        state: "allocated",
+        delta: -qty,
+        // Already enforced via assertAvailable; skipping the second check
+        // avoids a needless extra DB round-trip in the hot path.
+        enforceNonNegative: false
+      });
+      await writeMovement(tx.movements, {
+        skuId,
+        locationId,
+        fromState: "allocated",
+        toState: null,
+        qty,
+        reasonCode: options.reasonCode ?? "fulfillment",
+        sourceType: options.sourceType,
+        sourceId: options.sourceId,
+        note: options.note
+      });
+    });
+  }
+  /**
+   * Move `qty` of `available` stock from `fromLocationId` to
+   * `toLocationId`. Writes two movement rows — one for the `transfer_out`
+   * leg, one for the `transfer_in` leg — so the audit log preserves the
+   * lineage in both directions. Throws {@link InsufficientStockError} if
+   * source available stock would go negative.
+   *
+   * Both legs (level writes + movement rows) run inside one transaction
+   * — a failure mid-`transfer` rolls back the source debit so there's no
+   * "ghost stock disappearance" (source decremented, destination never
+   * credited).
+   */
+  async transfer(skuId, fromLocationId, toLocationId, qty, options = {}) {
+    assertPositiveQty(qty, "transfer");
+    if (fromLocationId === toLocationId) {
+      throw new Error(
+        `transfer: fromLocationId and toLocationId must differ (got ${fromLocationId})`
+      );
+    }
+    await this.runAtomically(async (tx) => {
+      await assertAvailable(tx.levels, skuId, fromLocationId, "available", qty);
+      await adjustLevel(tx.levels, {
+        skuId,
+        locationId: fromLocationId,
+        state: "available",
+        delta: -qty,
+        enforceNonNegative: false
+      });
+      await writeMovement(tx.movements, {
+        skuId,
+        locationId: fromLocationId,
+        fromState: "available",
+        toState: null,
+        qty,
+        reasonCode: options.reasonCode ?? "transfer_out",
+        sourceType: options.sourceType,
+        sourceId: options.sourceId,
+        note: options.note
+      });
+      await adjustLevel(tx.levels, {
+        skuId,
+        locationId: toLocationId,
+        state: "available",
+        delta: qty
+      });
+      await writeMovement(tx.movements, {
+        skuId,
+        locationId: toLocationId,
+        fromState: null,
+        toState: "available",
+        qty,
+        reasonCode: options.reasonCode ?? "transfer_in",
+        sourceType: options.sourceType,
+        sourceId: options.sourceId,
+        note: options.note
+      });
+    });
+  }
+  /**
+   * Apply a positive or negative `delta` to a level row. Used for cycle
+   * counts and one-off corrections; `delta=+5` adds five units,
+   * `delta=-2` removes two. By default the adjustment targets
+   * `available` stock; pass an explicit `state` to adjust a different
+   * bucket (e.g. `'damaged'` after a quality-control reclassification).
+   *
+   * Adjusting by `0` is rejected as a probable programming error — the
+   * caller almost always meant a non-zero delta and a no-op write would
+   * still cost an audit row.
+   */
+  async adjust(skuId, locationId, delta, options = {}) {
+    if (!Number.isFinite(delta) || delta === 0) {
+      throw new Error(
+        `adjust: delta must be a non-zero finite number (got ${delta})`
+      );
+    }
+    const state = options.state ?? "available";
+    await this.runAtomically(async (tx) => {
+      if (delta < 0) {
+        await assertAvailable(tx.levels, skuId, locationId, state, -delta);
+      }
+      await adjustLevel(tx.levels, {
+        skuId,
+        locationId,
+        state,
+        delta,
+        enforceNonNegative: false
+      });
+      await writeMovement(tx.movements, {
+        skuId,
+        locationId,
+        fromState: delta < 0 ? state : null,
+        toState: delta > 0 ? state : null,
+        qty: Math.abs(delta),
+        reasonCode: options.reasonCode ?? "adjustment",
+        sourceType: options.sourceType,
+        sourceId: options.sourceId,
+        note: options.note
+      });
+    });
+  }
+}
+async function assertAvailable(levels, skuId, locationId, state, requested) {
+  const level = await levels.getLevel(skuId, locationId, state);
+  const available = level ? Number(level.qty ?? 0) : 0;
+  if (available < requested) {
+    throw new InsufficientStockError(
+      skuId,
+      locationId,
+      state,
+      requested,
+      available
+    );
+  }
+}
+async function transitionState(tx, args) {
+  await assertAvailable(
+    tx.levels,
+    args.skuId,
+    args.locationId,
+    args.fromState,
+    args.qty
+  );
+  await adjustLevel(tx.levels, {
+    skuId: args.skuId,
+    locationId: args.locationId,
+    state: args.fromState,
+    delta: -args.qty,
+    enforceNonNegative: false
+  });
+  await adjustLevel(tx.levels, {
+    skuId: args.skuId,
+    locationId: args.locationId,
+    state: args.toState,
+    delta: args.qty
+  });
+  await writeMovement(tx.movements, {
+    skuId: args.skuId,
+    locationId: args.locationId,
+    fromState: args.fromState,
+    toState: args.toState,
+    qty: args.qty,
+    reasonCode: args.reasonCode,
+    sourceType: args.sourceType,
+    sourceId: args.sourceId,
+    note: args.note
+  });
+}
+async function adjustLevel(levels, options) {
+  const enforce = options.enforceNonNegative ?? options.delta < 0;
+  const existing = await levels.getLevel(
+    options.skuId,
+    options.locationId,
+    options.state
+  );
+  const previous = existing ? Number(existing.qty ?? 0) : 0;
+  const next = previous + options.delta;
+  if (enforce && next < 0) {
+    throw new InsufficientStockError(
+      options.skuId,
+      options.locationId,
+      options.state,
+      Math.abs(options.delta),
+      previous
+    );
+  }
+  if (existing) {
+    existing.qty = next;
+    await existing.save();
+    return existing;
+  }
+  const level = await levels.create({
+    skuId: options.skuId,
+    locationId: options.locationId,
+    state: options.state,
+    qty: next
+  });
+  return level;
+}
+async function writeMovement(movements, options) {
+  await movements.create({
+    skuId: options.skuId,
+    locationId: options.locationId,
+    fromState: options.fromState,
+    toState: options.toState,
+    qty: options.qty,
+    reasonCode: options.reasonCode,
+    sourceType: options.sourceType ?? "",
+    sourceId: options.sourceId ?? "",
+    note: options.note ?? "",
+    occurredAt: /* @__PURE__ */ new Date()
+  });
+}
+function assertPositiveQty(qty, op) {
+  if (!Number.isFinite(qty) || qty <= 0) {
+    throw new Error(`${op}: qty must be a positive finite number (got ${qty})`);
+  }
+}
+let warnedNonTransactional = false;
+function warnNonTransactional() {
+  if (warnedNonTransactional) return;
+  warnedNonTransactional = true;
+  logger$1.warn(
+    "[@happyvertical/smrt-inventory] StockService: underlying SQL adapter does not expose `transaction()`. Stock mutations are degrading to non-atomic serial writes — partial failures may leave the materialized level and the audit ledger out of sync. Upgrade @happyvertical/sql to >= 0.74.0 or use one of its built-in adapters."
+  );
+}
+async function createStockService(options) {
+  return StockService.create(options);
+}
+const logger = createLogger({ level: "info" });
+async function installInventoryDispatchHandlers(options) {
+  const {
+    dispatchBus,
+    installContractReserved = true,
+    installFulfillmentShipped = true
+  } = options;
+  const stockService = options.stockService ?? await buildStockService(options);
+  const installed = [];
+  if (installContractReserved) {
+    const handler = async (payload, metadata) => {
+      await handleContractCreated(
+        stockService,
+        payload,
+        metadata
+      );
+    };
+    dispatchBus.on("contract:created", handler);
+    installed.push({ pattern: "contract:created", handler });
+  }
+  if (installFulfillmentShipped) {
+    const handler = async (payload, metadata) => {
+      await handleFulfillmentShipped(
+        stockService,
+        payload,
+        metadata
+      );
+    };
+    dispatchBus.on("fulfillment:shipped", handler);
+    installed.push({ pattern: "fulfillment:shipped", handler });
+  }
+  return {
+    stockService,
+    dispose() {
+      for (const entry of installed) {
+        dispatchBus.off(entry.pattern, entry.handler);
+      }
+      installed.length = 0;
+    }
+  };
+}
+async function handleContractCreated(stockService, payload, metadata) {
+  const reason = malformedContractPayloadReason(payload);
+  if (reason || !payload) {
+    warnMalformedPayload(
+      "contract:created",
+      payload,
+      metadata,
+      reason ?? "payload is null/undefined"
+    );
+    return;
+  }
+  if (!areLinesWellFormed(payload.lines)) {
+    warnMalformedPayload(
+      "contract:created",
+      payload,
+      metadata,
+      "one or more entries in `lines` are null/undefined or missing required fields (skuId: string, locationId: string, qty: finite number)"
+    );
+    return;
+  }
+  const baseOptions = {
+    sourceType: "Contract",
+    sourceId: payload.contractId,
+    note: metadata.source ? `auto-reserve via ${metadata.source}` : void 0
+  };
+  await stockService.withTransaction(async (tx) => {
+    for (const line of payload.lines) {
+      await tx.reserve(line.skuId, line.locationId, line.qty, baseOptions);
+    }
+  });
+}
+async function handleFulfillmentShipped(stockService, payload, metadata) {
+  const reason = malformedFulfillmentPayloadReason(payload);
+  if (reason || !payload) {
+    warnMalformedPayload(
+      "fulfillment:shipped",
+      payload,
+      metadata,
+      reason ?? "payload is null/undefined"
+    );
+    return;
+  }
+  if (!areLinesWellFormed(payload.lines)) {
+    warnMalformedPayload(
+      "fulfillment:shipped",
+      payload,
+      metadata,
+      "one or more entries in `lines` are null/undefined or missing required fields (skuId: string, locationId: string, qty: finite number)"
+    );
+    return;
+  }
+  const baseOptions = {
+    sourceType: "Fulfillment",
+    sourceId: payload.fulfillmentId,
+    note: metadata.source ? `auto-fulfill via ${metadata.source}` : void 0
+  };
+  await stockService.withTransaction(async (tx) => {
+    for (const line of payload.lines) {
+      await tx.fulfill(line.skuId, line.locationId, line.qty, baseOptions);
+    }
+  });
+}
+function malformedContractPayloadReason(payload) {
+  if (!payload || typeof payload !== "object") {
+    return "payload is null/undefined or not an object";
+  }
+  if (!payload.contractId || typeof payload.contractId !== "string") {
+    return "missing or non-string `contractId` (required for audit-trail source attribution)";
+  }
+  if (!Array.isArray(payload.lines)) {
+    return "missing or non-array `lines`";
+  }
+  return null;
+}
+function malformedFulfillmentPayloadReason(payload) {
+  if (!payload || typeof payload !== "object") {
+    return "payload is null/undefined or not an object";
+  }
+  if (!payload.fulfillmentId || typeof payload.fulfillmentId !== "string") {
+    return "missing or non-string `fulfillmentId` (required for audit-trail source attribution)";
+  }
+  if (!Array.isArray(payload.lines)) {
+    return "missing or non-array `lines`";
+  }
+  return null;
+}
+function areLinesWellFormed(lines) {
+  for (const line of lines) {
+    if (!line) return false;
+    if (typeof line.skuId !== "string" || !line.skuId) return false;
+    if (typeof line.locationId !== "string" || !line.locationId) return false;
+    if (typeof line.qty !== "number" || !Number.isFinite(line.qty))
+      return false;
+  }
+  return true;
+}
+function warnMalformedPayload(signal, payload, metadata, reason) {
+  logger.warn(
+    `[@happyvertical/smrt-inventory] dispatch handler ignored a ${signal} event with a malformed payload (${reason}). Source: ${metadata.source ?? "<unknown>"}; payload keys: ${payload && typeof payload === "object" ? Object.keys(payload).join(",") : typeof payload}`
+  );
+}
+async function buildStockService(options) {
+  if (!options.db) {
+    throw new Error(
+      "installInventoryDispatchHandlers: either `stockService` or `db` is required"
+    );
+  }
+  return createStockService({ db: options.db });
+}
+export {
+  InsufficientStockError,
+  InventoryLocation,
+  InventoryLocationCollection,
+  StockLevel,
+  StockLevelCollection,
+  StockMovement,
+  StockMovementCollection,
+  StockService,
+  createStockService,
+  installInventoryDispatchHandlers
+};
+//# sourceMappingURL=index.js.map