@happyvertical/smrt-manufacturing 0.30.0

package/dist/index.js

@@ -0,0 +1,810 @@
+import { ObjectRegistry, field, smrt, SmrtObject, SmrtCollection } from "@happyvertical/smrt-core";
+import { tenantId, TenantScoped } from "@happyvertical/smrt-tenancy";
+import { createStockService } from "@happyvertical/smrt-inventory";
+import { BomNotFoundError, NoActiveBomForProductError } from "./types.js";
+import { createLogger } from "@happyvertical/logger";
+ObjectRegistry.registerPackageManifest(
+  new URL("./manifest.json", import.meta.url)
+);
+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 BillOfMaterials = class extends SmrtObject {
+  tenantId = null;
+  productId = "";
+  version = 1;
+  /**
+   * Date from which this BOM is intended to take effect for new production
+   * runs. Optional — older BOMs imported from legacy systems may have no
+   * effective date on file.
+   */
+  effectiveDate = null;
+  status = "draft";
+  /**
+   * Optional free-form notes shown in admin UIs (revision reason, source
+   * document reference, sign-off chain, etc.).
+   */
+  notes = "";
+  /**
+   * ISO 4217 currency code for cost rollups. Mostly a hint for the rollup
+   * service — defaults to `'USD'` so older imports without a currency
+   * still produce sensible numbers.
+   */
+  currency = "USD";
+  constructor(options = {}) {
+    super(options);
+    if (options.tenantId !== void 0) this.tenantId = options.tenantId;
+    if (options.productId !== void 0) this.productId = options.productId;
+    if (options.version !== void 0) this.version = options.version;
+    if (options.effectiveDate !== void 0) {
+      this.effectiveDate = options.effectiveDate === null ? null : options.effectiveDate instanceof Date ? options.effectiveDate : new Date(options.effectiveDate);
+    }
+    if (options.status !== void 0) this.status = options.status;
+    if (options.notes !== void 0) this.notes = options.notes;
+    if (options.currency !== void 0) this.currency = options.currency;
+  }
+};
+__decorateClass$1([
+  tenantId({ nullable: true })
+], BillOfMaterials.prototype, "tenantId", 2);
+__decorateClass$1([
+  field({ required: true })
+], BillOfMaterials.prototype, "productId", 2);
+__decorateClass$1([
+  field({ required: true })
+], BillOfMaterials.prototype, "version", 2);
+__decorateClass$1([
+  field({ required: true })
+], BillOfMaterials.prototype, "status", 2);
+BillOfMaterials = __decorateClass$1([
+  TenantScoped({ mode: "optional" }),
+  smrt({
+    tableName: "manufacturing_boms",
+    // Natural key: one BOM per (product, version) per tenant. Re-saving the
+    // same combination is an upsert rather than a UNIQUE violation.
+    conflictColumns: ["product_id", "version", "tenant_id"],
+    api: { include: ["list", "get", "create", "update"] },
+    mcp: { include: ["list", "get"] },
+    cli: true
+  })
+], BillOfMaterials);
+class BillOfMaterialsCollection extends SmrtCollection {
+  static _itemClass = BillOfMaterials;
+  /**
+   * Return every BOM for the given upstream product id, newest version
+   * first. Useful for "show me all revisions of this product's recipe"
+   * admin screens.
+   */
+  async findByProduct(productId) {
+    return this.list({ where: { productId }, orderBy: "version DESC" });
+  }
+  /**
+   * Return the currently `active` BOM for the given product, or `null` if
+   * none has been activated yet. When multiple `active` rows exist (which
+   * should not happen but can arise during partial migrations), the
+   * highest-version row wins.
+   */
+  async findActiveForProduct(productId) {
+    const matches = await this.list({
+      where: { productId, status: "active" },
+      orderBy: "version DESC",
+      limit: 1
+    });
+    return matches[0] ?? null;
+  }
+  /**
+   * Return every BOM with the given lifecycle status across all products.
+   * Mostly useful for admin dashboards (e.g. "show every draft BOM").
+   */
+  async findByStatus(status) {
+    return this.list({ where: { status }, orderBy: "productId ASC" });
+  }
+}
+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 BomLine = class extends SmrtObject {
+  tenantId = null;
+  bomId = "";
+  componentSkuId = "";
+  qtyPerUnit = 0;
+  /**
+   * Unit of measure for {@link qtyPerUnit}. Open-ended string so the
+   * framework does not constrain the vocabulary — `'yards'`, `'each'`,
+   * `'grams'`, `'kg'`, `'m'`, `'litres'`, `'sq_ft'`, anything.
+   *
+   * Conventions follow the upstream `Material.uom` value when applicable.
+   */
+  uom = "each";
+  wastePercent = 0;
+  /**
+   * Optional free-form notes — e.g. "primary structural component",
+   * "60-second cure", or "matched batch only".
+   */
+  notes = "";
+  constructor(options = {}) {
+    super(options);
+    if (options.tenantId !== void 0) this.tenantId = options.tenantId;
+    if (options.bomId !== void 0) this.bomId = options.bomId;
+    if (options.componentSkuId !== void 0)
+      this.componentSkuId = options.componentSkuId;
+    if (options.qtyPerUnit !== void 0) this.qtyPerUnit = options.qtyPerUnit;
+    if (options.uom !== void 0) this.uom = options.uom;
+    if (options.wastePercent !== void 0)
+      this.wastePercent = options.wastePercent;
+    if (options.notes !== void 0) this.notes = options.notes;
+  }
+  /**
+   * Effective quantity consumed per produced unit, including waste. Used
+   * by {@link BomService} for cost rollups and requirements explosions.
+   *
+   * `effectiveQty = qtyPerUnit * (1 + wastePercent / 100)`
+   */
+  effectiveQtyPerUnit() {
+    const qty = Number(this.qtyPerUnit ?? 0);
+    const waste = Number(this.wastePercent ?? 0);
+    return qty * (1 + waste / 100);
+  }
+};
+__decorateClass([
+  tenantId({ nullable: true })
+], BomLine.prototype, "tenantId", 2);
+__decorateClass([
+  field({ required: true })
+], BomLine.prototype, "bomId", 2);
+__decorateClass([
+  field({ required: true })
+], BomLine.prototype, "componentSkuId", 2);
+__decorateClass([
+  field({ type: "decimal" })
+], BomLine.prototype, "qtyPerUnit", 2);
+__decorateClass([
+  field({ type: "decimal" })
+], BomLine.prototype, "wastePercent", 2);
+BomLine = __decorateClass([
+  TenantScoped({ mode: "optional" }),
+  smrt({
+    tableName: "manufacturing_bom_lines",
+    // Natural key: one row per `(bom, component)` per tenant. Re-saving the
+    // same combination updates the row in place rather than violating the
+    // UNIQUE constraint. Callers that want to declare two distinct lines for
+    // the same component (e.g. "main" vs "trim" passes) should use distinct
+    // component SKUs or model the variants in inventory.
+    conflictColumns: ["bom_id", "component_sku_id", "tenant_id"],
+    api: { include: ["list", "get", "create", "update"] },
+    mcp: { include: ["list", "get"] },
+    cli: true
+  })
+], BomLine);
+class BomLineCollection extends SmrtCollection {
+  static _itemClass = BomLine;
+  /**
+   * Return every line that belongs to the given BOM. Caller-stable order
+   * helps make cost rollups and requirements explosions deterministic.
+   */
+  async findByBom(bomId) {
+    return this.list({ where: { bomId }, orderBy: "componentSkuId ASC" });
+  }
+  /**
+   * Return every line that references the given component SKU across all
+   * BOMs. Useful for "where is this material used?" admin screens and for
+   * cost-change impact analysis (a price hike on a raw material affects
+   * every BOM in the result).
+   */
+  async findByComponent(componentSkuId) {
+    return this.list({ where: { componentSkuId }, orderBy: "bomId ASC" });
+  }
+}
+class BomService {
+  constructor(boms, lines, stockService, costResolver) {
+    this.boms = boms;
+    this.lines = lines;
+    this.stockService = stockService;
+    this.costResolver = costResolver;
+  }
+  boms;
+  lines;
+  stockService;
+  costResolver;
+  /** Factory — prefer {@link createBomService}. */
+  static async create(options) {
+    const stockService = options.stockService ?? await buildStockService$1(options);
+    const sharedDb = options.db ?? stockService.db;
+    const [boms, lines] = await Promise.all([
+      BillOfMaterialsCollection.create({ db: sharedDb }),
+      BomLineCollection.create({ db: sharedDb })
+    ]);
+    return new BomService(boms, lines, stockService, options.costResolver);
+  }
+  /**
+   * Walk every {@link BomLine} for the given BOM, resolve each line's
+   * component cost, apply waste, and return the rolled-up material cost
+   * per produced unit along with a per-line breakdown.
+   *
+   * Throws {@link BomNotFoundError} when the BOM does not exist.
+   *
+   * Lines whose cost cannot be resolved contribute `0` to the total and
+   * set `costUnavailable: true` on their breakdown row; the aggregate
+   * `hasMissingCosts` flag mirrors this so callers can surface a UI
+   * warning.
+   */
+  async computeMaterialCost(bomId) {
+    const bom = await this.requireBom(bomId);
+    const lines = await this.lines.findByBom(bomId);
+    const lineBreakdown = [];
+    let totalCost = 0;
+    let hasMissingCosts = false;
+    for (const line of lines) {
+      const effectiveQty = line.effectiveQtyPerUnit();
+      const resolved = await this.resolveCost(line.componentSkuId);
+      const unitCost = resolved ?? 0;
+      const costUnavailable = resolved === null || resolved === void 0;
+      const lineCost = unitCost * effectiveQty;
+      if (costUnavailable) {
+        hasMissingCosts = true;
+      } else {
+        totalCost += lineCost;
+      }
+      lineBreakdown.push({
+        componentSkuId: line.componentSkuId,
+        qtyPerUnit: Number(line.qtyPerUnit ?? 0),
+        wastePercent: Number(line.wastePercent ?? 0),
+        effectiveQty,
+        unitCost,
+        lineCost,
+        uom: line.uom,
+        costUnavailable
+      });
+    }
+    return {
+      bomId,
+      totalCost,
+      currency: bom.currency || "USD",
+      lineBreakdown,
+      hasMissingCosts
+    };
+  }
+  /**
+   * Return a "shopping list" of materials needed to produce `qty` units of
+   * the parent product against the given BOM. Lines that reference the
+   * same component SKU are summed so each `componentSkuId` appears once
+   * in the result.
+   *
+   * Does NOT mutate stock — purely a planning helper. Use
+   * {@link ProductionService.consumeMaterials} when you're ready to write
+   * stock movements.
+   *
+   * Throws {@link BomNotFoundError} when the BOM does not exist; throws a
+   * plain `Error` when `qty` is not a positive finite number.
+   */
+  async explodeRequirements(bomId, qty) {
+    assertPositiveQty$1(qty, "explodeRequirements");
+    await this.requireBom(bomId);
+    const lines = await this.lines.findByBom(bomId);
+    const aggregate = /* @__PURE__ */ new Map();
+    for (const line of lines) {
+      const effectiveQty = line.effectiveQtyPerUnit() * qty;
+      const existing = aggregate.get(line.componentSkuId);
+      if (existing) {
+        existing.totalQty += effectiveQty;
+      } else {
+        aggregate.set(line.componentSkuId, {
+          componentSkuId: line.componentSkuId,
+          totalQty: effectiveQty,
+          uom: line.uom
+        });
+      }
+    }
+    return Array.from(aggregate.values());
+  }
+  /**
+   * Check whether the requirements for producing `qty` units against the
+   * given BOM are currently satisfied by available stock. Returns
+   * `{ ok: true, shortages: [] }` when every component has enough
+   * `available` stock across all locations; `{ ok: false, shortages: [...] }`
+   * with one entry per insufficient component otherwise.
+   *
+   * Available stock is summed across every location (the planning
+   * question is "do we have it at all?"; the operational question of
+   * "where do we pull from?" is left to the caller of
+   * {@link ProductionService.consumeMaterials}).
+   *
+   * Throws {@link BomNotFoundError} when the BOM does not exist.
+   */
+  async canProduce(bomId, qty) {
+    const requirements = await this.explodeRequirements(bomId, qty);
+    const availabilities = await Promise.all(
+      requirements.map(async (requirement) => ({
+        requirement,
+        available: await this.stockService.levels.totalForSku(
+          requirement.componentSkuId,
+          "available"
+        )
+      }))
+    );
+    const shortages = [];
+    for (const { requirement, available } of availabilities) {
+      if (available < requirement.totalQty) {
+        shortages.push({
+          componentSkuId: requirement.componentSkuId,
+          requested: requirement.totalQty,
+          available
+        });
+      }
+    }
+    if (shortages.length === 0) {
+      return { ok: true, shortages: [] };
+    }
+    return { ok: false, shortages };
+  }
+  // ─────────────────────────────────────────────────────────────────────────
+  // Internal helpers
+  // ─────────────────────────────────────────────────────────────────────────
+  /**
+   * Fetch a BOM by id or throw {@link BomNotFoundError}. Centralises the
+   * "missing BOM" error path so callers don't have to repeat the check.
+   */
+  async requireBom(bomId) {
+    if (!bomId) throw new BomNotFoundError(bomId);
+    const bom = await this.boms.get(bomId);
+    if (!bom) throw new BomNotFoundError(bomId);
+    return bom;
+  }
+  /**
+   * Run the supplied {@link ComponentCostResolver} for the given component
+   * SKU. Returns `null` when no resolver is registered or when the
+   * resolver returns `null` / `undefined`.
+   */
+  async resolveCost(componentSkuId) {
+    if (!this.costResolver) return null;
+    const value = await this.costResolver(componentSkuId);
+    if (value === null || value === void 0) return null;
+    if (!Number.isFinite(value)) return null;
+    return Number(value);
+  }
+}
+function assertPositiveQty$1(qty, op) {
+  if (!Number.isFinite(qty) || qty <= 0) {
+    throw new Error(`${op}: qty must be a positive finite number (got ${qty})`);
+  }
+}
+async function buildStockService$1(options) {
+  if (!options.db) {
+    throw new Error(
+      "BomService.create: either `db` or `stockService` is required"
+    );
+  }
+  return createStockService({ db: options.db });
+}
+async function createBomService(options) {
+  return BomService.create(options);
+}
+class ProductionService {
+  constructor(boms, lines, stockService) {
+    this.boms = boms;
+    this.lines = lines;
+    this.stockService = stockService;
+  }
+  boms;
+  lines;
+  stockService;
+  /** Factory — prefer {@link createProductionService}. */
+  static async create(options) {
+    const stockService = options.stockService ?? await buildStockService(options);
+    const sharedDb = options.db ?? stockService.db;
+    const [boms, lines] = await Promise.all([
+      BillOfMaterialsCollection.create({ db: sharedDb }),
+      BomLineCollection.create({ db: sharedDb })
+    ]);
+    return new ProductionService(boms, lines, stockService);
+  }
+  /**
+   * Walk every BOM line for the production order's BOM and deduct
+   * `effectiveQtyPerUnit() * qty` from `available` at `locationId`. Each
+   * deduction goes through {@link StockService.adjust} with `sourceType:
+   * 'ProductionOrder'` and `sourceId: order.id`. Returns the list of
+   * movements emitted so callers can log / surface them.
+   *
+   * **Atomic across lines**: all per-line deductions and their audit
+   * movements run inside a single `stockService.withTransaction(...)`
+   * scope. An `InsufficientStockError` on line N+1 rolls back lines 1..N
+   * so production-order posting never leaves materials half-consumed.
+   * Pre-flight with {@link BomService.canProduce} when you'd rather know
+   * upfront than discover the shortfall mid-run.
+   *
+   * Throws {@link NoActiveBomForProductError} if no BOM id is supplied
+   * on the order *and* no active BOM exists for the order's `productId`.
+   * Throws {@link BomNotFoundError} if `order.bomId` is supplied but
+   * doesn't resolve. Throws plain `Error` on missing `locationId`,
+   * non-positive `qty`, or when both `order.bomId` and `order.productId`
+   * are absent (a programmer error — neither input identifies a BOM).
+   * Re-throws `InsufficientStockError` from `StockService.adjust` if a
+   * line would drive `available` below zero.
+   */
+  async consumeMaterials(order, options) {
+    const ctx = await this.prepareConsume(order, options);
+    return this.stockService.withTransaction(
+      async (tx) => this.consumeMaterialsWith(tx, ctx)
+    );
+  }
+  /**
+   * Receive `qty` of the finished SKU into `available` at `locationId`.
+   * Goes through {@link StockService.receive} with `sourceType:
+   * 'ProductionOrder'` and `sourceId: order.id`. Returns a single
+   * {@link ProduceResult} describing what landed.
+   *
+   * Throws plain `Error` on missing required arguments or non-positive
+   * `qty`.
+   */
+  async produceFinishedGoods(order, options) {
+    const ctx = prepareProduce(order, options);
+    return this.stockService.withTransaction(
+      async (tx) => this.produceFinishedGoodsWith(tx, ctx)
+    );
+  }
+  /**
+   * Atomically consume materials AND receive finished goods for one
+   * production run.
+   *
+   * Both calls share a single `stockService.withTransaction(...)` scope:
+   *
+   * - Materials are deducted line-by-line via {@link StockService.adjust}.
+   * - Finished goods are received via {@link StockService.receive}.
+   * - If ANY step throws — a BOM-line shortage, the produce-leg adapter
+   *   failing, a tenancy mismatch surfaced by an interceptor — every
+   *   write in the transaction rolls back. The materials are restored
+   *   and the finished SKU's `available` row is unchanged. Callers
+   *   never observe "materials deducted but finished goods missing".
+   *
+   * Use this when consume + produce should be one indivisible event —
+   * e.g. a make-to-stock workflow posting `production_order:completed`
+   * where the shop floor step is invisible to the ledger.
+   *
+   * The two-call form (call {@link consumeMaterials} then {@link
+   * produceFinishedGoods} separately) is still appropriate when the
+   * factory step is a real wall-clock gap that other observers need to
+   * see — work-in-progress dashboards, partial-run reporting, etc.
+   *
+   * Throws the same errors as the individual methods: missing args
+   * (plain `Error`), unresolvable BOM ({@link BomNotFoundError} /
+   * {@link NoActiveBomForProductError}), or `InsufficientStockError`
+   * if a line would drive `available` below zero.
+   */
+  async runProduction(order, options) {
+    const consumeCtx = await this.prepareConsume(order, options.consume);
+    const produceCtx = prepareProduce(order, options.produce);
+    return this.stockService.withTransaction(async (tx) => {
+      const consumed = await this.consumeMaterialsWith(tx, consumeCtx);
+      const produced = await this.produceFinishedGoodsWith(tx, produceCtx);
+      return { consumed, produced };
+    });
+  }
+  // ─────────────────────────────────────────────────────────────────────────
+  // Internal helpers
+  // ─────────────────────────────────────────────────────────────────────────
+  /**
+   * Validate consume args, resolve the BOM + lines, and pre-compute the
+   * mutation attribution. Anything that can throw without a tx open
+   * happens here so the transaction we open later doesn't have to roll
+   * back over a validation miss.
+   */
+  async prepareConsume(order, options) {
+    assertLocationId(options.locationId, "consumeMaterials");
+    assertPositiveQty(options.qty, "consumeMaterials");
+    const orderId = order.id ?? "";
+    if (!orderId) {
+      throw new Error(
+        "consumeMaterials: order.id is required for source attribution"
+      );
+    }
+    const bom = await this.resolveBom(order);
+    const lines = await this.lines.findByBom(bom.id);
+    return {
+      orderId,
+      lines,
+      runQty: options.qty,
+      locationId: options.locationId,
+      mutationOptions: {
+        sourceType: "ProductionOrder",
+        sourceId: orderId,
+        reasonCode: options.reasonCode ?? "production_consume",
+        note: options.note
+      }
+    };
+  }
+  /**
+   * Execute the consume leg against a caller-supplied tx-bound
+   * {@link StockService}. Public entry points (`consumeMaterials`,
+   * `runProduction`) open the tx and call through here. Each per-line
+   * `tx.adjust(...)` shares the same transaction so a shortfall on
+   * line N+1 rolls back lines 1..N.
+   */
+  async consumeMaterialsWith(tx, ctx) {
+    const emitted = [];
+    for (const line of ctx.lines) {
+      const qty = line.effectiveQtyPerUnit() * ctx.runQty;
+      if (qty <= 0) continue;
+      await tx.adjust(
+        line.componentSkuId,
+        ctx.locationId,
+        -qty,
+        ctx.mutationOptions
+      );
+      emitted.push({
+        componentSkuId: line.componentSkuId,
+        qty,
+        locationId: ctx.locationId
+      });
+    }
+    return emitted;
+  }
+  /**
+   * Execute the produce leg against a caller-supplied tx-bound
+   * {@link StockService}. Public entry points (`produceFinishedGoods`,
+   * `runProduction`) open the tx and call through here.
+   */
+  async produceFinishedGoodsWith(tx, ctx) {
+    await tx.receive(
+      ctx.finishedSkuId,
+      ctx.locationId,
+      ctx.qty,
+      ctx.mutationOptions
+    );
+    return {
+      finishedSkuId: ctx.finishedSkuId,
+      qty: ctx.qty,
+      locationId: ctx.locationId
+    };
+  }
+  /**
+   * Resolve the BOM for a production order. Order of preference:
+   *
+   * 1. Explicit `order.bomId` if supplied — the caller pinned a specific
+   *    revision; we honor that pin or fail. We deliberately do NOT fall
+   *    back to the active BOM when `order.bomId` is stale or mistyped,
+   *    because silently switching recipes would have the production run
+   *    consume materials against a different BOM than the order locked.
+   * 2. The active BOM for `order.productId`.
+   *
+   * Throws {@link BomNotFoundError} when an explicit `order.bomId` is
+   * supplied but doesn't resolve to a row.
+   *
+   * Throws {@link NoActiveBomForProductError} when no `bomId` was supplied
+   * and the product has no active BOM.
+   *
+   * Throws plain `Error` when neither `order.bomId` nor `order.productId`
+   * is supplied — there's nothing to resolve against, so we surface that
+   * as a programmer error with a distinct message rather than overload
+   * `NoActiveBomForProductError` with an empty product id.
+   */
+  async resolveBom(order) {
+    if (order.bomId) {
+      const bom = await this.boms.get(order.bomId);
+      if (!bom) throw new BomNotFoundError(order.bomId);
+      return bom;
+    }
+    const productId = order.productId ?? "";
+    if (!productId) {
+      throw new Error(
+        "consumeMaterials: order.productId is required when order.bomId is not supplied"
+      );
+    }
+    const active = await this.boms.findActiveForProduct(productId);
+    if (!active) throw new NoActiveBomForProductError(productId);
+    return active;
+  }
+}
+function prepareProduce(order, options) {
+  assertLocationId(options.locationId, "produceFinishedGoods");
+  assertPositiveQty(options.qty, "produceFinishedGoods");
+  if (!options.finishedSkuId) {
+    throw new Error(
+      "produceFinishedGoods: finishedSkuId is required (the production order references a productId; the caller picks which SKU is being produced)"
+    );
+  }
+  const orderId = order.id ?? "";
+  if (!orderId) {
+    throw new Error(
+      "produceFinishedGoods: order.id is required for source attribution"
+    );
+  }
+  return {
+    orderId,
+    finishedSkuId: options.finishedSkuId,
+    qty: options.qty,
+    locationId: options.locationId,
+    mutationOptions: {
+      sourceType: "ProductionOrder",
+      sourceId: orderId,
+      reasonCode: options.reasonCode ?? "production_produce",
+      note: options.note
+    }
+  };
+}
+function assertPositiveQty(qty, op) {
+  if (!Number.isFinite(qty) || qty <= 0) {
+    throw new Error(`${op}: qty must be a positive finite number (got ${qty})`);
+  }
+}
+function assertLocationId(locationId, op) {
+  if (!locationId || typeof locationId !== "string") {
+    throw new Error(`${op}: locationId is required`);
+  }
+}
+async function buildStockService(options) {
+  if (!options.db) {
+    throw new Error(
+      "ProductionService.create: either `db` or `stockService` is required"
+    );
+  }
+  return createStockService({ db: options.db });
+}
+async function createProductionService(options) {
+  return ProductionService.create(options);
+}
+const logger = createLogger({ level: "info" });
+async function installManufacturingDispatchHandlers(options) {
+  const {
+    dispatchBus,
+    installProductionPosted = true,
+    installProductionCompleted = false,
+    producedOnPosted = false
+  } = options;
+  const productionService = options.productionService ?? await buildProductionService(options);
+  const installed = [];
+  if (installProductionPosted) {
+    const shouldProduceOnPosted = producedOnPosted && !installProductionCompleted;
+    const handler = async (payload, metadata) => {
+      await handleProductionPosted(
+        productionService,
+        payload,
+        metadata,
+        shouldProduceOnPosted
+      );
+    };
+    dispatchBus.on("production_order:posted", handler);
+    installed.push({ pattern: "production_order:posted", handler });
+  }
+  if (installProductionCompleted) {
+    const handler = async (payload, metadata) => {
+      await handleProductionCompleted(
+        productionService,
+        payload,
+        metadata
+      );
+    };
+    dispatchBus.on("production_order:completed", handler);
+    installed.push({ pattern: "production_order:completed", handler });
+  }
+  return {
+    productionService,
+    dispose() {
+      for (const entry of installed) {
+        dispatchBus.off(entry.pattern, entry.handler);
+      }
+      installed.length = 0;
+    }
+  };
+}
+async function handleProductionPosted(productionService, payload, metadata, shouldProduce) {
+  const postedReason = malformedProductionPayloadReason(payload);
+  if (postedReason || !payload) {
+    warnMalformedPayload(
+      "production_order:posted",
+      payload,
+      metadata,
+      postedReason ?? "payload is null/undefined"
+    );
+    return;
+  }
+  if (shouldProduce && !payload.finishedSkuId) {
+    throw new Error(
+      `production_order:posted handler: producedOnPosted is enabled but payload.finishedSkuId is missing (productionOrderId=${payload.productionOrderId}). Either supply finishedSkuId on the event, or disable producedOnPosted and emit production_order:completed separately.`
+    );
+  }
+  const order = {
+    id: payload.productionOrderId,
+    productId: payload.productId,
+    bomId: payload.bomId
+  };
+  const consumeNote = metadata.source ? `auto-consume via ${metadata.source}` : void 0;
+  if (shouldProduce && payload.finishedSkuId) {
+    const produceNote = metadata.source ? `auto-produce via ${metadata.source}` : void 0;
+    await productionService.runProduction(order, {
+      consume: {
+        locationId: payload.locationId,
+        qty: payload.qty,
+        note: consumeNote
+      },
+      produce: {
+        locationId: payload.locationId,
+        qty: payload.qty,
+        finishedSkuId: payload.finishedSkuId,
+        note: produceNote
+      }
+    });
+    return;
+  }
+  await productionService.consumeMaterials(order, {
+    locationId: payload.locationId,
+    qty: payload.qty,
+    note: consumeNote
+  });
+}
+async function handleProductionCompleted(productionService, payload, metadata) {
+  const completedReason = malformedProductionPayloadReason(payload);
+  if (completedReason || !payload) {
+    warnMalformedPayload(
+      "production_order:completed",
+      payload,
+      metadata,
+      completedReason ?? "payload is null/undefined"
+    );
+    return;
+  }
+  await productionService.produceFinishedGoods(
+    { id: payload.productionOrderId },
+    {
+      locationId: payload.locationId,
+      qty: payload.qty,
+      finishedSkuId: payload.finishedSkuId,
+      note: metadata.source ? `auto-produce via ${metadata.source}` : void 0
+    }
+  );
+}
+function malformedProductionPayloadReason(payload) {
+  if (!payload || typeof payload !== "object") {
+    return "payload is null/undefined or not an object";
+  }
+  if (!payload.productionOrderId || typeof payload.productionOrderId !== "string") {
+    return "missing or non-string `productionOrderId` (required for audit-trail source attribution)";
+  }
+  return null;
+}
+function warnMalformedPayload(signal, payload, metadata, reason) {
+  logger.warn(
+    `[@happyvertical/smrt-manufacturing] 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 buildProductionService(options) {
+  if (options.stockService) {
+    return createProductionService({
+      stockService: options.stockService,
+      ...options.db ? { db: options.db } : {}
+    });
+  }
+  if (!options.db) {
+    throw new Error(
+      "installManufacturingDispatchHandlers: one of `productionService`, `stockService`, or `db` is required"
+    );
+  }
+  return createProductionService({ db: options.db });
+}
+export {
+  BillOfMaterials,
+  BillOfMaterialsCollection,
+  BomLine,
+  BomLineCollection,
+  BomNotFoundError,
+  BomService,
+  NoActiveBomForProductError,
+  ProductionService,
+  createBomService,
+  createProductionService,
+  installManufacturingDispatchHandlers
+};
+//# sourceMappingURL=index.js.map