@happyvertical/smrt-inventory 0.57.16 → 0.57.18

package/dist/services/StockService.d.ts

@@ -24,6 +24,15 @@
  * `console.warn`. Tests and consumers that observe that warning should
  * upgrade their adapter.
  *
+ * **Lots**: pass `lotId` in the options of any mutation and the same deltas
+ * are applied to {@link LotStockLevel} rows keyed by
+ * `(lotId, locationId, state)`, with the same non-negative rule, and the
+ * lot is stamped on every movement written. SKU-level balances behave
+ * exactly as without a lot. Create lots with {@link LotService}; compose
+ * both through a shared transaction (`stock.withTransaction`, then
+ * `createLotService({ db: tx.db })`) to receive a lot and its stock
+ * atomically.
+ *
  * Callers should never reach into the level or movement collections
  * directly to mutate balances — doing so silently desyncs the audit
  * ledger and breaks cycle counts.
@@ -40,7 +49,7 @@
  * @packageDocumentation
  */
 import { type DatabaseConfig } from '@happyvertical/smrt-core';
-import { InventoryLocationCollection, StockLevelCollection, StockMovementCollection } from '../collections/index.js';
+import { InventoryLocationCollection, LotCollection, LotStockLevelCollection, StockLevelCollection, StockMovementCollection } from '../collections/index.js';
 import type { StockLevel } from '../models/StockLevel.js';
 import type { StockMovementReason, StockState } from '../types.js';
 /**
@@ -56,8 +65,12 @@ export declare class InsufficientStockError extends Error {
     readonly state: StockState;
     readonly requested: number;
     readonly available: number;
+    /** Set when the shortfall is in a lot's balance rather than the SKU's. */
+    readonly lotId?: string | undefined;
     name: string;
-    constructor(skuId: string, locationId: string, state: StockState, requested: number, available: number);
+    constructor(skuId: string, locationId: string, state: StockState, requested: number, available: number, 
+    /** Set when the shortfall is in a lot's balance rather than the SKU's. */
+    lotId?: string | undefined);
 }
 /**
  * Options shared by every {@link StockService} method that wants to leave
@@ -65,6 +78,11 @@ export declare class InsufficientStockError extends Error {
  * pattern in {@link StockMovement.sourceType} / {@link StockMovement.sourceId}.
  */
 export interface StockMutationOptions {
+    /**
+     * Track this mutation against a {@link Lot}. The lot must exist and, when
+     * it names a SKU, that SKU must match (else {@link LotMismatchError}).
+     */
+    lotId?: string | null;
     /** Cross-package tag, e.g. `'Contract'`, `'Fulfillment'`, `'CycleCount'`. */
     sourceType?: string;
     /** Cross-package id of the row that caused this mutation. */
@@ -131,6 +149,10 @@ export declare class StockService {
     readonly levels: StockLevelCollection;
     readonly movements: StockMovementCollection;
     readonly locations: InventoryLocationCollection;
+    /** Per-lot balances, mutated only by this service. */
+    readonly lotLevels: LotStockLevelCollection;
+    /** Lookup of lots for validation; created through {@link LotService}. */
+    readonly lots: LotCollection;
     /**
      * Marks a service instance handed to a {@link withTransaction}
      * callback. Public mutation methods on a tx-bound instance skip
@@ -171,6 +193,7 @@ export declare class StockService {
      * callback), reuse it; otherwise open a fresh one.
      */
     private runAtomically;
+    private txCollections;
     /**
      * Add `qty` to available stock at the given location. Used for
      * purchase-order receipts, customer returns going back into available

package/dist/services/StockService.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"StockService.d.ts","sourceRoot":"","sources":["../../src/services/StockService.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"StockService.d.ts","sourceRoot":"","sources":["../../src/services/StockService.ts"],"names":[],"mappings":"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"}

package/dist/services/index.d.ts

@@ -4,5 +4,7 @@
  * @packageDocumentation
  */
 export { type ContractCreatedLine, type ContractCreatedPayload, type FulfillmentShippedLine, type FulfillmentShippedPayload, type InstalledInventoryDispatchHandlers, type InstallInventoryDispatchHandlersOptions, installInventoryDispatchHandlers, } from './dispatch-handlers.js';
+export { type AttachDocumentInput, createLotService, type LotChangeOptions, LotService, type LotServiceOptions, type ReceiveLotInput, type RecordUsageInput, type TraceNode, type TraceOptions, } from './LotService.js';
+export { DuplicateLotError, LotCorrectionError, LotInUseError, LotMismatchError, LotNotFoundError, } from './lot-errors.js';
 export { createStockService, InsufficientStockError, type StockMutationOptions, StockService, type StockServiceOptions, } from './StockService.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/services/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/services/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,sBAAsB,EAC3B,KAAK,sBAAsB,EAC3B,KAAK,yBAAyB,EAC9B,KAAK,kCAAkC,EACvC,KAAK,uCAAuC,EAC5C,gCAAgC,GACjC,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,kBAAkB,EAClB,sBAAsB,EACtB,KAAK,oBAAoB,EACzB,YAAY,EACZ,KAAK,mBAAmB,GACzB,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/services/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,sBAAsB,EAC3B,KAAK,sBAAsB,EAC3B,KAAK,yBAAyB,EAC9B,KAAK,kCAAkC,EACvC,KAAK,uCAAuC,EAC5C,gCAAgC,GACjC,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,KAAK,mBAAmB,EACxB,gBAAgB,EAChB,KAAK,gBAAgB,EACrB,UAAU,EACV,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,SAAS,EACd,KAAK,YAAY,GAClB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EAClB,aAAa,EACb,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,kBAAkB,EAClB,sBAAsB,EACtB,KAAK,oBAAoB,EACzB,YAAY,EACZ,KAAK,mBAAmB,GACzB,MAAM,mBAAmB,CAAC"}

package/dist/services/lot-errors.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Errors thrown by {@link LotService} and by {@link StockService} when a
+ * mutation names a lot. Kept in their own module so both services can
+ * import them without a cycle.
+ *
+ * @packageDocumentation
+ */
+/** The lot id does not exist (or belongs to another tenant). */
+export declare class LotNotFoundError extends Error {
+    readonly lotId: string;
+    name: string;
+    constructor(lotId: string);
+}
+/** A stock mutation named a lot that belongs to a different SKU. */
+export declare class LotMismatchError extends Error {
+    readonly lotId: string;
+    readonly lotSkuId: string;
+    readonly skuId: string;
+    name: string;
+    constructor(lotId: string, lotSkuId: string, skuId: string);
+}
+/**
+ * A unique lot or serial with this number already exists. Carries the
+ * existing lot's id so the caller can link to it.
+ */
+export declare class DuplicateLotError extends Error {
+    readonly lotNumber: string;
+    readonly existingLotId: string | null;
+    name: string;
+    constructor(lotNumber: string, existingLotId: string | null);
+}
+/** An exclusive lot is already in use by a different consumer. */
+export declare class LotInUseError extends Error {
+    readonly lotId: string;
+    readonly consumerType: string;
+    readonly consumerId: string;
+    name: string;
+    constructor(lotId: string, consumerType: string, consumerId: string);
+}
+/** A correction was refused: missing or oversized reason, or nothing changes. */
+export declare class LotCorrectionError extends Error {
+    name: string;
+}
+//# sourceMappingURL=lot-errors.d.ts.map

package/dist/services/lot-errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lot-errors.d.ts","sourceRoot":"","sources":["../../src/services/lot-errors.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,gEAAgE;AAChE,qBAAa,gBAAiB,SAAQ,KAAK;aAGb,KAAK,EAAE,MAAM;IAFhC,IAAI,SAAsB;gBAEP,KAAK,EAAE,MAAM;CAG1C;AAED,oEAAoE;AACpE,qBAAa,gBAAiB,SAAQ,KAAK;aAIvB,KAAK,EAAE,MAAM;aACb,QAAQ,EAAE,MAAM;aAChB,KAAK,EAAE,MAAM;IALtB,IAAI,SAAsB;gBAGjB,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM;CAIhC;AAED;;;GAGG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;aAIxB,SAAS,EAAE,MAAM;aACjB,aAAa,EAAE,MAAM,GAAG,IAAI;IAJrC,IAAI,SAAuB;gBAGlB,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE,MAAM,GAAG,IAAI;CAI/C;AAED,kEAAkE;AAClE,qBAAa,aAAc,SAAQ,KAAK;aAIpB,KAAK,EAAE,MAAM;aACb,YAAY,EAAE,MAAM;aACpB,UAAU,EAAE,MAAM;IAL3B,IAAI,SAAmB;gBAGd,KAAK,EAAE,MAAM,EACb,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM;CAIrC;AAED,iFAAiF;AACjF,qBAAa,kBAAmB,SAAQ,KAAK;IAClC,IAAI,SAAwB;CACtC"}