@happyvertical/smrt-inventory 0.51.31 → 0.51.33

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

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

package/dist/services/dispatch-handlers.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Opt-in DispatchBus subscribers that bridge upstream packages to the
+ * {@link StockService}.
+ *
+ * **Off by default.** The package never auto-subscribes — consumer apps
+ * call {@link installInventoryDispatchHandlers} from their `smrt.ts`
+ * wiring once they have decided they want automatic stock motion when
+ * contracts are created and fulfilments ship.
+ *
+ * The production-order leg (`production_order:posted` → consume
+ * materials + produce SKUs) is deliberately *not* installed here; that
+ * subscriber lives in `@happyvertical/smrt-manufacturing` (see issue
+ * #1250) and depends on the BOM model that ships alongside it.
+ *
+ * @packageDocumentation
+ */
+import type { DatabaseConfig, DispatchBus } from '@happyvertical/smrt-core';
+import { type StockService } from './StockService.js';
+/**
+ * Shape of a single reserved line in a `contract:created` payload. The
+ * producer (typically `@happyvertical/smrt-commerce`) packs one entry
+ * per line that needs stock motion; everything else (taxes, fees,
+ * non-physical items) should be filtered upstream.
+ */
+export interface ContractCreatedLine {
+    skuId: string;
+    locationId: string;
+    qty: number;
+}
+/**
+ * Shape of the `contract:created` payload this handler expects. Carries
+ * the contract id (used for source attribution on the audit row) and
+ * the list of line items to reserve.
+ */
+export interface ContractCreatedPayload {
+    contractId: string;
+    lines: ContractCreatedLine[];
+}
+/**
+ * Shape of a single shipped line in a `fulfillment:shipped` payload.
+ */
+export interface FulfillmentShippedLine {
+    skuId: string;
+    locationId: string;
+    qty: number;
+}
+/**
+ * Shape of the `fulfillment:shipped` payload this handler expects.
+ * Producers emit one per shipped fulfilment; the handler fulfils each
+ * line against the level created by the matching `contract:created`
+ * reservation.
+ */
+export interface FulfillmentShippedPayload {
+    fulfillmentId: string;
+    lines: FulfillmentShippedLine[];
+}
+/**
+ * Options accepted by {@link installInventoryDispatchHandlers}.
+ *
+ * Provide either a pre-built {@link StockService} (when sharing one
+ * across multiple subsystems) or a `db` for the helper to construct one
+ * on first use.
+ */
+export type InstallInventoryDispatchHandlersOptions = {
+    /**
+     * Bus to subscribe on. Typically the app-wide `DispatchBus` created in
+     * the application's `smrt.ts`.
+     */
+    dispatchBus: DispatchBus;
+    /**
+     * When `true` (default), install the `contract:created` handler.
+     * Producers should publish a {@link ContractCreatedPayload}.
+     */
+    installContractReserved?: boolean;
+    /**
+     * When `true` (default), install the `fulfillment:shipped` handler.
+     * Producers should publish a {@link FulfillmentShippedPayload}.
+     */
+    installFulfillmentShipped?: boolean;
+} & ({
+    stockService: StockService;
+    db?: DatabaseConfig;
+} | {
+    db: DatabaseConfig;
+    stockService?: undefined;
+});
+/**
+ * Result handle returned by {@link installInventoryDispatchHandlers}.
+ * Call `dispose()` to detach the subscribers (mainly useful in tests
+ * and on graceful shutdown).
+ */
+export interface InstalledInventoryDispatchHandlers {
+    /** Resolved StockService — useful for follow-up writes in the same scope. */
+    stockService: StockService;
+    /** Detach every installed subscriber. Idempotent. */
+    dispose(): void;
+}
+/**
+ * Subscribe a {@link StockService}-driven handler to the relevant signals
+ * on the given {@link DispatchBus}. Returns a disposer for tests and
+ * shutdown hooks.
+ *
+ * @example
+ * ```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,
+ * });
+ * ```
+ */
+export declare function installInventoryDispatchHandlers(options: InstallInventoryDispatchHandlersOptions): Promise<InstalledInventoryDispatchHandlers>;
+//# sourceMappingURL=dispatch-handlers.d.ts.map

package/dist/services/dispatch-handlers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch-handlers.d.ts","sourceRoot":"","sources":["../../src/services/dispatch-handlers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,KAAK,EACV,cAAc,EACd,WAAW,EAGZ,MAAM,0BAA0B,CAAC;AAElC,OAAO,EAAsB,KAAK,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAI1E;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,mBAAmB,EAAE,CAAC;CAC9B;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;;;GAKG;AACH,MAAM,WAAW,yBAAyB;IACxC,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,sBAAsB,EAAE,CAAC;CACjC;AAED;;;;;;GAMG;AACH,MAAM,MAAM,uCAAuC,GAAG;IACpD;;;OAGG;IACH,WAAW,EAAE,WAAW,CAAC;IACzB;;;OAGG;IACH,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAClC;;;OAGG;IACH,yBAAyB,CAAC,EAAE,OAAO,CAAC;CACrC,GAAG,CACA;IAAE,YAAY,EAAE,YAAY,CAAC;IAAC,EAAE,CAAC,EAAE,cAAc,CAAA;CAAE,GACnD;IAAE,EAAE,EAAE,cAAc,CAAC;IAAC,YAAY,CAAC,EAAE,SAAS,CAAA;CAAE,CACnD,CAAC;AAEF;;;;GAIG;AACH,MAAM,WAAW,kCAAkC;IACjD,6EAA6E;IAC7E,YAAY,EAAE,YAAY,CAAC;IAC3B,qDAAqD;IACrD,OAAO,IAAI,IAAI,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,gCAAgC,CACpD,OAAO,EAAE,uCAAuC,GAC/C,OAAO,CAAC,kCAAkC,CAAC,CA6C7C"}

package/dist/services/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Service exports for `@happyvertical/smrt-inventory`.
+ *
+ * @packageDocumentation
+ */
+export { type ContractCreatedLine, type ContractCreatedPayload, type FulfillmentShippedLine, type FulfillmentShippedPayload, type InstalledInventoryDispatchHandlers, type InstallInventoryDispatchHandlersOptions, installInventoryDispatchHandlers, } from './dispatch-handlers.js';
+export { createStockService, InsufficientStockError, type StockMutationOptions, StockService, type StockServiceOptions, } from './StockService.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +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"}

package/dist/smrt-knowledge.json

@@ -3,12 +3,12 @@
   "sensitiveFieldsExcluded": true,
   "generatedAt": "1970-01-01T00:00:00.000Z",
   "packageName": "@happyvertical/smrt-inventory",
-  "packageVersion": "0.51.31",
+  "packageVersion": "0.51.33",
   "sourceManifestPath": "dist/manifest.json",
   "agentDocPath": "AGENTS.md",
   "sourceHashes": {
-    "manifest": "0e0888e560559d7345556f07af49c461355fdf4b6f6fbe4e67b1606f7d975844",
-    "packageJson": "fc89f9d871efc0e27f20bfecd5359a71be4ba266f062d331691de5f52b874431",
+    "manifest": "78ad406940e0da8c9c516d9370561baff35f342c429c1ffa9f4ac06d412bbaf9",
+    "packageJson": "29e834e5876c142b8de3ebf51888ed4bc379c17a4f00c1efe06c50a0a8417cfc",
     "agents": "a771bf16d21cabbe43a77d5cb87ca7dedbf2e68d1928cf804cf4fefaad7a765f"
   },
   "exports": [
@@ -23,7 +23,7 @@
     "@happyvertical/sql": "catalog:",
     "@happyvertical/smrt-vitest": "workspace:*",
     "@types/node": "24.13.6",
-    "typescript": "5.9.3",
+    "typescript": "6.0.3",
     "vite": "8.1.4",
     "vitest": "4.1.10"
   },

package/dist/types.d.ts

@@ -1,55 +1,51 @@
-/**
- * Shared types for @happyvertical/smrt-inventory.
- *
- * These are deliberately industry-neutral: the same vocabulary serves
- * apparel, furniture, automotive, CPG, electronics, and any other domain
- * that tracks countable units across locations.
- *
- * @packageDocumentation
- */
-
-/**
- * Open-ended classifier for an InventoryLocation. The framework does not
- * special-case any value — pass whatever taxonomy your application needs.
- *
- * The strings listed here are conventions, not an exhaustive enum:
- * - `warehouse` — fulfillment warehouse
- * - `factory` — manufacturing site
- * - `retail` — storefront / point-of-sale
- * - `in_transit` — virtual location for stock that has left A but not yet
- *   arrived at B; balances `transfer()` semantics
- * - `virtual` — any other non-physical bucket (returns staging, scrap,
- *   consignment pool)
- */
-export declare type InventoryLocationKind = string;
-
-/**
- * Why a StockMovement was written.
- *
- * Each {@link StockService} method writes one movement with a `reasonCode`
- * drawn from this list. Free-form `string` is also accepted so consumers
- * can introduce vocabulary specific to their business (e.g. `'shrink'`,
- * `'sample'`, `'consignment_out'`) without forking the package.
- */
-export declare type StockMovementReason = 'receipt' | 'reservation' | 'release' | 'fulfillment' | 'transfer_out' | 'transfer_in' | 'adjustment' | 'production_consume' | 'production_produce' | (string & {});
-
-/**
- * Logical state of a quantity of stock at a `(skuId, locationId)` pair.
- *
- * StockLevel rows are tuples of `(skuId, locationId, state)`, so a single
- * SKU at a single location can simultaneously have non-zero quantities in
- * several states (e.g. 50 available, 10 allocated, 3 damaged).
- *
- * - `available` — on hand and free to allocate.
- * - `allocated` — reserved against a contract, order, or production plan;
- *   physically still on site but no longer free to sell.
- * - `wip` — work-in-progress: consumed materials inside an active
- *   production order, not yet emitted as finished goods.
- * - `qc_hold` — held pending quality control; not available to allocate
- *   or ship until released.
- * - `damaged` — damaged or otherwise unsellable; kept on the books for
- *   shrinkage accounting until written off.
- */
-export declare type StockState = 'available' | 'allocated' | 'wip' | 'qc_hold' | 'damaged';
-
-export { }
+/**
+ * Shared types for @happyvertical/smrt-inventory.
+ *
+ * These are deliberately industry-neutral: the same vocabulary serves
+ * apparel, furniture, automotive, CPG, electronics, and any other domain
+ * that tracks countable units across locations.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Logical state of a quantity of stock at a `(skuId, locationId)` pair.
+ *
+ * StockLevel rows are tuples of `(skuId, locationId, state)`, so a single
+ * SKU at a single location can simultaneously have non-zero quantities in
+ * several states (e.g. 50 available, 10 allocated, 3 damaged).
+ *
+ * - `available` — on hand and free to allocate.
+ * - `allocated` — reserved against a contract, order, or production plan;
+ *   physically still on site but no longer free to sell.
+ * - `wip` — work-in-progress: consumed materials inside an active
+ *   production order, not yet emitted as finished goods.
+ * - `qc_hold` — held pending quality control; not available to allocate
+ *   or ship until released.
+ * - `damaged` — damaged or otherwise unsellable; kept on the books for
+ *   shrinkage accounting until written off.
+ */
+export type StockState = 'available' | 'allocated' | 'wip' | 'qc_hold' | 'damaged';
+/**
+ * Open-ended classifier for an InventoryLocation. The framework does not
+ * special-case any value — pass whatever taxonomy your application needs.
+ *
+ * The strings listed here are conventions, not an exhaustive enum:
+ * - `warehouse` — fulfillment warehouse
+ * - `factory` — manufacturing site
+ * - `retail` — storefront / point-of-sale
+ * - `in_transit` — virtual location for stock that has left A but not yet
+ *   arrived at B; balances `transfer()` semantics
+ * - `virtual` — any other non-physical bucket (returns staging, scrap,
+ *   consignment pool)
+ */
+export type InventoryLocationKind = string;
+/**
+ * Why a StockMovement was written.
+ *
+ * Each {@link StockService} method writes one movement with a `reasonCode`
+ * drawn from this list. Free-form `string` is also accepted so consumers
+ * can introduce vocabulary specific to their business (e.g. `'shrink'`,
+ * `'sample'`, `'consignment_out'`) without forking the package.
+ */
+export type StockMovementReason = 'receipt' | 'reservation' | 'release' | 'fulfillment' | 'transfer_out' | 'transfer_in' | 'adjustment' | 'production_consume' | 'production_produce' | (string & {});
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,UAAU,GAClB,WAAW,GACX,WAAW,GACX,KAAK,GACL,SAAS,GACT,SAAS,CAAC;AAEd;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,qBAAqB,GAAG,MAAM,CAAC;AAE3C;;;;;;;GAOG;AACH,MAAM,MAAM,mBAAmB,GAC3B,SAAS,GACT,aAAa,GACb,SAAS,GACT,aAAa,GACb,cAAc,GACd,aAAa,GACb,YAAY,GACZ,oBAAoB,GACpB,oBAAoB,GACpB,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@happyvertical/smrt-inventory",
-  "version": "0.51.31",
+  "version": "0.51.33",
   "description": "Multi-location stock tracking for the SMRT framework — Sku, InventoryLocation, StockLevel, StockMovement, and a stock-mutation service",
   "type": "module",
   "main": "./dist/index.js",
@@ -20,14 +20,14 @@
   },
   "dependencies": {
     "@happyvertical/logger": "^0.94.1",
-    "@happyvertical/smrt-core": "0.51.31",
-    "@happyvertical/smrt-tenancy": "0.51.31",
+    "@happyvertical/smrt-core": "0.51.33",
+    "@happyvertical/smrt-tenancy": "0.51.33",
     "@happyvertical/sql": "^0.94.1"
   },
   "devDependencies": {
-    "@happyvertical/smrt-vitest": "0.51.31",
+    "@happyvertical/smrt-vitest": "0.51.33",
     "@types/node": "24.13.6",
-    "typescript": "5.9.3",
+    "typescript": "6.0.3",
     "vite": "8.1.4",
     "vitest": "4.1.10"
   },