@classytic/flow 0.1.4

package/dist/stock-move-group-C0DqUfPY.mjs

@@ -0,0 +1,88 @@
+import { t as FlowError } from "./base-MWBqRFM2.mjs";
+import { o as MoveAlreadyPostedError } from "./domain-errors-D7S9ydNF.mjs";
+import { r as isValidMoveTransition } from "./move-status-DkaFp2GD.mjs";
+//#region src/domain/constants/virtual-locations.ts
+/** Package defaults — used when the host app doesn't provide overrides. */
+const DEFAULT_VIRTUAL_LOCATIONS = {
+	vendor: "vendor",
+	customer: "customer",
+	adjustment: "inventory_loss",
+	transit: "transit",
+	scrap: "scrap"
+};
+/**
+* Resolve the final virtual location map by merging host-app overrides
+* on top of the package defaults.
+*/
+function resolveVirtualLocations(overrides) {
+	return Object.freeze({
+		...DEFAULT_VIRTUAL_LOCATIONS,
+		...overrides
+	});
+}
+/**
+* Build the list of location IDs that should skip the negative-stock guard
+* because they represent stock entering or leaving the system boundary.
+*/
+function buildVirtualSourceTypes(locations) {
+	return Object.freeze([
+		locations.vendor,
+		locations.customer,
+		locations.adjustment,
+		locations.scrap,
+		locations.transit
+	]);
+}
+//#endregion
+//#region src/domain/errors/invalid-transition.error.ts
+var InvalidTransitionError = class extends FlowError {
+	code = "INVALID_TRANSITION";
+	httpStatus = 422;
+	constructor(entityType, entityId, from, to) {
+		super(`Invalid transition for ${entityType} ${entityId}: ${from} → ${to}`);
+		this.entityType = entityType;
+		this.entityId = entityId;
+		this.from = from;
+		this.to = to;
+	}
+};
+//#endregion
+//#region src/domain/errors/reservation-expired.error.ts
+var ReservationExpiredError = class extends FlowError {
+	code = "RESERVATION_EXPIRED";
+	httpStatus = 410;
+	constructor(reservationId) {
+		super(`Reservation ${reservationId} has expired and can no longer be consumed`);
+		this.reservationId = reservationId;
+	}
+};
+//#endregion
+//#region src/domain/entities/stock-move.ts
+/**
+* Validate a move status transition. Throws if invalid.
+*/
+function assertMoveTransition(move, targetStatus) {
+	if (move.status === "done") throw new MoveAlreadyPostedError(move._id);
+	if (!isValidMoveTransition(move.status, targetStatus)) throw new InvalidTransitionError("StockMove", move._id, move.status, targetStatus);
+}
+//#endregion
+//#region src/domain/entities/stock-move-group.ts
+const MOVE_GROUP_STATUS_TRANSITIONS = {
+	draft: ["confirmed", "cancelled"],
+	confirmed: [
+		"allocated",
+		"in_progress",
+		"cancelled"
+	],
+	allocated: ["in_progress", "cancelled"],
+	in_progress: [
+		"done",
+		"partially_done",
+		"cancelled"
+	],
+	partially_done: ["done", "cancelled"],
+	done: [],
+	cancelled: []
+};
+//#endregion
+export { DEFAULT_VIRTUAL_LOCATIONS as a, InvalidTransitionError as i, assertMoveTransition as n, buildVirtualSourceTypes as o, ReservationExpiredError as r, resolveVirtualLocations as s, MOVE_GROUP_STATUS_TRANSITIONS as t };

package/dist/stock-package-BIarxbDS.d.mts

@@ -0,0 +1,19 @@
+//#region src/domain/entities/stock-package.d.ts
+interface StockPackage {
+  _id: string;
+  organizationId: string;
+  name: string;
+  barcode: string;
+  packageTypeId?: string;
+  parentPackageId?: string;
+  locationId?: string;
+  destinationLocationId?: string;
+  baseWeight?: number;
+  maxWeight?: number;
+  packageUse: 'disposable' | 'reusable';
+  metadata?: Record<string, unknown>;
+  createdAt?: Date;
+  updatedAt?: Date;
+}
+//#endregion
+export { StockPackage as t };

package/dist/stock-quant-CZhgvTu7.d.mts

@@ -0,0 +1,41 @@
+import { i as StockStatus } from "./index-CulWO137.mjs";
+
+//#region src/domain/entities/stock-quant.d.ts
+/**
+ * Materialized stock balance per unique identity tuple.
+ * Derived from move history, not the source of truth.
+ *
+ * Unique identity: { organizationId, skuRef, locationId, lotId, ownerRef }
+ */
+interface StockQuant {
+  _id: string;
+  organizationId: string;
+  skuRef: string;
+  locationId: string;
+  lotId?: string;
+  ownerRef?: string;
+  stockStatus: StockStatus;
+  quantityOnHand: number;
+  quantityReserved: number;
+  quantityAvailable: number;
+  quantityIncoming?: number;
+  quantityOutgoing?: number;
+  inDate: Date;
+  lotExpiresAt?: Date;
+  unitCost?: number;
+  lastMovementAt?: Date;
+  createdAt?: Date;
+  updatedAt?: Date;
+}
+/**
+ * The 5-field unique identity for a quant.
+ */
+interface QuantIdentity {
+  organizationId: string;
+  skuRef: string;
+  locationId: string;
+  lotId?: string;
+  ownerRef?: string;
+}
+//#endregion
+export { StockQuant as n, QuantIdentity as t };

package/dist/tenant-guard-6Ne-BILP.mjs

@@ -0,0 +1,12 @@
+import { t as TenantIsolationError } from "./tenant-isolation.error-D3OcKUdx.mjs";
+//#region src/utils/tenant-guard.ts
+/**
+* Assert that the given context carries a valid organizationId.
+* Must be called at the entry point of every service method to enforce
+* tenant isolation before any database access.
+*/
+function assertTenantContext(ctx) {
+	if (!ctx.organizationId) throw new TenantIsolationError();
+}
+//#endregion
+export { assertTenantContext as t };

package/dist/tenant-isolation.error-D3OcKUdx.mjs

@@ -0,0 +1,11 @@
+import { t as FlowError } from "./base-MWBqRFM2.mjs";
+//#region src/domain/errors/tenant-isolation.error.ts
+var TenantIsolationError = class extends FlowError {
+	code = "TENANT_ISOLATION";
+	httpStatus = 403;
+	constructor(message = "Tenant isolation violation: organizationId mismatch or missing") {
+		super(message);
+	}
+};
+//#endregion
+export { TenantIsolationError as t };

package/dist/trace.service-B9vAh-l-.d.mts

@@ -0,0 +1,55 @@
+import { n as MovePort, r as StockMove } from "./move.port-Qg1CYp7h.mjs";
+import { t as FlowContext } from "./index-DFF0GJ4J.mjs";
+import { n as StockLot, t as LotPort } from "./lot.port-ChsmvZqs.mjs";
+import { r as QuantPort } from "./quant.port-BBa66PBT.mjs";
+
+//#region src/traceability/trace.service.d.ts
+interface TraceResult {
+  lot: StockLot;
+  currentLocations: Array<{
+    locationId: string;
+    quantity: number;
+  }>;
+  movementHistory: StockMove[];
+  totalQuantity: number;
+}
+interface RecallResult {
+  lot: StockLot;
+  affectedLocations: Array<{
+    locationId: string;
+    quantity: number;
+  }>;
+  shippedMoves: StockMove[];
+  totalInWarehouse: number;
+  totalShipped: number;
+}
+/**
+ * TraceService — lot and serial traceability queries.
+ * Aggregates data from lots, moves, and quants to produce full trace and recall reports.
+ */
+declare class TraceService {
+  private lotPort;
+  private movePort;
+  private quantPort;
+  constructor(lotPort: LotPort, movePort: MovePort, quantPort: QuantPort);
+  /**
+   * Trace a lot: find current locations, quantities, and full movement history.
+   */
+  traceLot(lotCode: string, skuRef: string, ctx: FlowContext): Promise<TraceResult | null>;
+  /**
+   * Trace a serial: identical to traceLot but resolves by serial code.
+   */
+  traceSerial(serialCode: string, skuRef: string, ctx: FlowContext): Promise<TraceResult | null>;
+  /**
+   * Recall a lot: determine affected warehouse locations and shipments to external locations.
+   */
+  recallLot(lotCode: string, skuRef: string, ctx: FlowContext): Promise<RecallResult | null>;
+  private buildTrace;
+  /**
+   * Find all moves that reference a lot — either through trackingAssignments.lotId
+   * or via the move-level filter.
+   */
+  private findMovesForLot;
+}
+//#endregion
+export { TraceResult as n, TraceService as r, RecallResult as t };

package/dist/trace.service-DE6Eh8_8.mjs

@@ -0,0 +1,71 @@
+//#region src/traceability/trace.service.ts
+/**
+* TraceService — lot and serial traceability queries.
+* Aggregates data from lots, moves, and quants to produce full trace and recall reports.
+*/
+var TraceService = class {
+	constructor(lotPort, movePort, quantPort) {
+		this.lotPort = lotPort;
+		this.movePort = movePort;
+		this.quantPort = quantPort;
+	}
+	/**
+	* Trace a lot: find current locations, quantities, and full movement history.
+	*/
+	async traceLot(lotCode, skuRef, ctx) {
+		const lot = await this.lotPort.findByCode(lotCode, skuRef, ctx);
+		if (!lot) return null;
+		return this.buildTrace(lot, ctx);
+	}
+	/**
+	* Trace a serial: identical to traceLot but resolves by serial code.
+	*/
+	async traceSerial(serialCode, skuRef, ctx) {
+		const lot = await this.lotPort.findBySerial(serialCode, skuRef, ctx);
+		if (!lot) return null;
+		return this.buildTrace(lot, ctx);
+	}
+	/**
+	* Recall a lot: determine affected warehouse locations and shipments to external locations.
+	*/
+	async recallLot(lotCode, skuRef, ctx) {
+		const lot = await this.lotPort.findByCode(lotCode, skuRef, ctx);
+		if (!lot) return null;
+		const [quants, moves] = await Promise.all([this.quantPort.findMany({ lotId: lot._id }, ctx), this.findMovesForLot(lot._id, ctx)]);
+		const affectedLocations = quants.filter((q) => q.quantityOnHand > 0).map((q) => ({
+			locationId: q.locationId,
+			quantity: q.quantityOnHand
+		}));
+		const totalInWarehouse = affectedLocations.reduce((sum, l) => sum + l.quantity, 0);
+		const shippedMoves = moves.filter((m) => m.operationType === "shipment");
+		return {
+			lot,
+			affectedLocations,
+			shippedMoves,
+			totalInWarehouse,
+			totalShipped: shippedMoves.reduce((sum, m) => sum + (m.quantityDone ?? m.quantityPlanned), 0)
+		};
+	}
+	async buildTrace(lot, ctx) {
+		const [quants, moves] = await Promise.all([this.quantPort.findMany({ lotId: lot._id }, ctx), this.findMovesForLot(lot._id, ctx)]);
+		const currentLocations = quants.filter((q) => q.quantityOnHand > 0).map((q) => ({
+			locationId: q.locationId,
+			quantity: q.quantityOnHand
+		}));
+		return {
+			lot,
+			currentLocations,
+			movementHistory: moves,
+			totalQuantity: currentLocations.reduce((sum, l) => sum + l.quantity, 0)
+		};
+	}
+	/**
+	* Find all moves that reference a lot — either through trackingAssignments.lotId
+	* or via the move-level filter.
+	*/
+	async findMovesForLot(lotId, ctx) {
+		return this.movePort.findMany({ "trackingAssignments.lotId": lotId }, ctx);
+	}
+};
+//#endregion
+export { TraceService as t };

package/dist/traceability/index.d.mts

@@ -0,0 +1,2 @@
+import { n as TraceResult, r as TraceService, t as RecallResult } from "../trace.service-B9vAh-l-.mjs";
+export { type RecallResult, type TraceResult, TraceService };

package/dist/traceability/index.mjs

@@ -0,0 +1,2 @@
+import { t as TraceService } from "../trace.service-DE6Eh8_8.mjs";
+export { TraceService };

package/dist/types/index.d.mts

@@ -0,0 +1,2 @@
+import { a as QueryOptions, i as PaginatedResult, n as FlowMode, r as ListQuery, t as FlowContext } from "../index-DFF0GJ4J.mjs";
+export { FlowContext, FlowMode, ListQuery, PaginatedResult, QueryOptions };

package/dist/types/index.mjs

@@ -0,0 +1 @@
+export {};

package/dist/unit-of-work.port-CWEkrDKu.d.mts

@@ -0,0 +1,17 @@
+//#region src/domain/ports/unit-of-work.port.d.ts
+/**
+ * Opaque transaction session handle.
+ * Services never inspect this. Repositories cast to mongoose.ClientSession.
+ */
+interface TransactionSession {
+  readonly _brand: 'TransactionSession';
+}
+/**
+ * Unit of Work — provides transactional boundaries.
+ * All state mutations that must be atomic go through withTransaction().
+ */
+interface UnitOfWork {
+  withTransaction<T>(fn: (session: TransactionSession) => Promise<T>): Promise<T>;
+}
+//#endregion
+export { UnitOfWork as n, TransactionSession as t };

package/dist/valuation/index.d.mts

@@ -0,0 +1,78 @@
+import { n as CostLayer } from "../cost-layer.port-iH9pvZqB.mjs";
+import { a as FifoEngine, i as ConsumptionResult, n as CreateCostLayerInput, r as InventoryValuation, t as CostLayerService } from "../cost-layer.service-DWmo9dQz.mjs";
+
+//#region src/valuation/fefo.engine.d.ts
+declare class FefoEngine {
+  private fifoEngine;
+  consume(layers: CostLayer[], quantity: number): ConsumptionResult;
+}
+//#endregion
+//#region src/valuation/landed-cost.service.d.ts
+type AllocationMethod = 'by_value' | 'by_quantity' | 'by_weight' | 'by_volume' | 'equal';
+interface LandedCostInput {
+  totalCost: number;
+  method: AllocationMethod;
+  items: Array<{
+    skuRef: string;
+    quantity: number;
+    value: number;
+    weight?: number;
+    volume?: number;
+  }>;
+}
+interface LandedCostAllocation {
+  items: Array<{
+    skuRef: string;
+    allocatedCost: number;
+    newUnitCost: number;
+  }>;
+  totalAllocated: number;
+}
+interface PostCapitalizeInput {
+  additionalCost: number;
+  method: AllocationMethod;
+  items: Array<{
+    skuRef: string;
+    currentQuantity: number;
+    quantitySold: number;
+    currentUnitCost: number;
+    originalReceiptQuantity: number;
+    value?: number;
+    weight?: number;
+    volume?: number;
+  }>;
+}
+interface PostCapitalizeItem {
+  skuRef: string;
+  allocatedCost: number;
+  additionalCostPerUnit: number;
+  newUnitCost: number;
+  cogsAdjustment: number;
+  remainingStockAdjustment: number;
+}
+interface PostCapitalizeResult {
+  items: PostCapitalizeItem[];
+  totalAdditionalCost: number;
+  totalCogsAdjustment: number;
+  totalRemainingStockAdjustment: number;
+}
+declare class LandedCostService {
+  allocate(input: LandedCostInput): LandedCostAllocation;
+  /**
+   * Post-capitalization — retroactively apply late cost invoices to already-received stock.
+   *
+   * When a freight/duty invoice arrives weeks after goods are received,
+   * this method distributes the cost across the original receipt items,
+   * recalculates unit costs, and separates the adjustment into:
+   * - COGS adjustment (for units already sold)
+   * - Remaining stock adjustment (for units still in inventory)
+   */
+  postCapitalize(input: PostCapitalizeInput): PostCapitalizeResult;
+}
+//#endregion
+//#region src/valuation/wac.engine.d.ts
+declare class WacEngine {
+  calculate(oldQty: number, oldCost: number, inQty: number, inCost: number): number;
+}
+//#endregion
+export { type AllocationMethod, type ConsumptionResult, CostLayerService, type CreateCostLayerInput, FefoEngine, FifoEngine, type InventoryValuation, type LandedCostAllocation, type LandedCostInput, LandedCostService, WacEngine };

package/dist/valuation/index.mjs

@@ -0,0 +1,103 @@
+import { n as FefoEngine, r as FifoEngine, t as CostLayerService } from "../cost-layer.service-BQ1bs-XN.mjs";
+//#region src/valuation/landed-cost.service.ts
+var LandedCostService = class {
+	allocate(input) {
+		const { totalCost, method, items } = input;
+		let allocations;
+		switch (method) {
+			case "by_value": {
+				const total = items.reduce((s, i) => s + i.value, 0);
+				allocations = items.map((i) => total > 0 ? i.value / total * totalCost : 0);
+				break;
+			}
+			case "by_quantity": {
+				const total = items.reduce((s, i) => s + i.quantity, 0);
+				allocations = items.map((i) => total > 0 ? i.quantity / total * totalCost : 0);
+				break;
+			}
+			case "by_weight": {
+				const total = items.reduce((s, i) => s + (i.weight ?? 0), 0);
+				allocations = items.map((i) => total > 0 ? (i.weight ?? 0) / total * totalCost : 0);
+				break;
+			}
+			case "by_volume": {
+				const total = items.reduce((s, i) => s + (i.volume ?? 0), 0);
+				allocations = items.map((i) => total > 0 ? (i.volume ?? 0) / total * totalCost : 0);
+				break;
+			}
+			case "equal":
+				allocations = items.length > 0 ? items.map(() => totalCost / items.length) : [];
+				break;
+			default: allocations = items.map(() => 0);
+		}
+		const diff = totalCost - allocations.reduce((s, a) => s + a, 0);
+		if (allocations.length > 0 && Math.abs(diff) > .001) allocations[allocations.length - 1] += diff;
+		return {
+			items: items.map((item, i) => ({
+				skuRef: item.skuRef,
+				allocatedCost: Math.round(allocations[i] * 100) / 100,
+				newUnitCost: item.quantity > 0 ? Math.round((item.value + allocations[i]) / item.quantity * 100) / 100 : 0
+			})),
+			totalAllocated: totalCost
+		};
+	}
+	/**
+	* Post-capitalization — retroactively apply late cost invoices to already-received stock.
+	*
+	* When a freight/duty invoice arrives weeks after goods are received,
+	* this method distributes the cost across the original receipt items,
+	* recalculates unit costs, and separates the adjustment into:
+	* - COGS adjustment (for units already sold)
+	* - Remaining stock adjustment (for units still in inventory)
+	*/
+	postCapitalize(input) {
+		const { additionalCost, method, items } = input;
+		const allocationItems = items.map((item) => ({
+			skuRef: item.skuRef,
+			quantity: item.originalReceiptQuantity,
+			value: item.currentUnitCost * item.originalReceiptQuantity,
+			weight: item.weight,
+			volume: item.volume
+		}));
+		const allocation = this.allocate({
+			totalCost: additionalCost,
+			method,
+			items: allocationItems
+		});
+		const resultItems = items.map((item, i) => {
+			const allocatedCost = allocation.items[i].allocatedCost;
+			const additionalCostPerUnit = item.originalReceiptQuantity > 0 ? Math.round(allocatedCost / item.originalReceiptQuantity * 100) / 100 : 0;
+			const newUnitCost = Math.round((item.currentUnitCost + additionalCostPerUnit) * 100) / 100;
+			const cogsAdjustment = Math.round(item.quantitySold * additionalCostPerUnit * 100) / 100;
+			const remainingStockAdjustment = Math.round((allocatedCost - cogsAdjustment) * 100) / 100;
+			return {
+				skuRef: item.skuRef,
+				allocatedCost,
+				additionalCostPerUnit,
+				newUnitCost,
+				cogsAdjustment,
+				remainingStockAdjustment
+			};
+		});
+		const totalSplit = resultItems.reduce((s, i) => s + i.cogsAdjustment + i.remainingStockAdjustment, 0);
+		const crossItemDiff = Math.round((additionalCost - totalSplit) * 100) / 100;
+		if (resultItems.length > 0 && Math.abs(crossItemDiff) > 0) resultItems[resultItems.length - 1].remainingStockAdjustment = Math.round((resultItems[resultItems.length - 1].remainingStockAdjustment + crossItemDiff) * 100) / 100;
+		return {
+			items: resultItems,
+			totalAdditionalCost: additionalCost,
+			totalCogsAdjustment: resultItems.reduce((s, i) => s + i.cogsAdjustment, 0),
+			totalRemainingStockAdjustment: resultItems.reduce((s, i) => s + i.remainingStockAdjustment, 0)
+		};
+	}
+};
+//#endregion
+//#region src/valuation/wac.engine.ts
+var WacEngine = class {
+	calculate(oldQty, oldCost, inQty, inCost) {
+		const totalQty = oldQty + inQty;
+		if (totalQty <= 0) return oldCost;
+		return Math.round((oldQty * oldCost + inQty * inCost) / totalQty * 1e4) / 1e4;
+	}
+};
+//#endregion
+export { CostLayerService, FefoEngine, FifoEngine, LandedCostService, WacEngine };

package/dist/valuation-policy-Dco8c9Vw.d.mts

@@ -0,0 +1,14 @@
+//#region src/domain/policies/valuation-policy.d.ts
+/**
+ * Valuation policy — config object, not a strategy interface.
+ * The valuation engine reads this.
+ */
+interface ValuationPolicy {
+  method: 'wac' | 'fifo' | 'fefo' | 'specific' | 'standard';
+  scope: 'organization' | 'node' | 'sku';
+  landedCostAllocation: 'by_value' | 'by_quantity' | 'by_weight' | 'by_volume' | 'equal';
+  negativeCostHandling: 'freeze_last' | 'zero' | 'error';
+  interNodeTransferCost: 'sender_cost' | 'standard_cost' | 'transfer_price';
+}
+//#endregion
+export { ValuationPolicy as t };

package/dist/virtual-locations-B9zXqPdi.d.mts

@@ -0,0 +1,38 @@
+//#region src/domain/constants/virtual-locations.d.ts
+/**
+ * Virtual location sentinels used by Flow services.
+ *
+ * These are string IDs that represent logical locations outside the
+ * physical warehouse graph. They appear in StockMove.sourceLocationId
+ * and StockMove.destinationLocationId but do not correspond to real
+ * Location documents.
+ *
+ * Host apps override these defaults via `FlowConfig.virtualLocations`.
+ */
+/** Shape of the virtual location map — every key has a string sentinel value. */
+interface VirtualLocationMap {
+  /** Source location for inbound receipts from external vendors. */
+  vendor: string;
+  /** Source location for customer returns / destination for outbound shipments. */
+  customer: string;
+  /** Catch-all for inventory adjustments (shrinkage, found stock, count reconciliation). */
+  adjustment: string;
+  /** Transit location for in-flight inter-branch transfers. */
+  transit: string;
+  /** Scrap / write-off destination. */
+  scrap: string;
+}
+/** Package defaults — used when the host app doesn't provide overrides. */
+declare const DEFAULT_VIRTUAL_LOCATIONS: VirtualLocationMap;
+/**
+ * Resolve the final virtual location map by merging host-app overrides
+ * on top of the package defaults.
+ */
+declare function resolveVirtualLocations(overrides?: Partial<VirtualLocationMap>): VirtualLocationMap;
+/**
+ * Build the list of location IDs that should skip the negative-stock guard
+ * because they represent stock entering or leaving the system boundary.
+ */
+declare function buildVirtualSourceTypes(locations: VirtualLocationMap): readonly string[];
+//#endregion
+export { resolveVirtualLocations as i, VirtualLocationMap as n, buildVirtualSourceTypes as r, DEFAULT_VIRTUAL_LOCATIONS as t };